@pipedream/topdesk 0.0.1 → 0.2.0

package/actions/create-incident/create-incident.mjs

@@ -0,0 +1,415 @@
+import app from "../../topdesk.app.mjs";
+
+export default {
+  key: "topdesk-create-incident",
+  name: "Create Incident",
+  description: "Creates a new incident. [See the documentation](https://developers.topdesk.com/explorer/?page=incident#/incident/createIncident)",
+  version: "0.0.2",
+  type: "action",
+  props: {
+    app,
+    callerLookupId: {
+      type: "string",
+      label: "Caller Lookup ID",
+      description: "Lookup value for filling in a registered caller's contact details (UUID). **Required** - you must specify either this field or provide caller details manually.",
+      propDefinition: [
+        app,
+        "personId",
+      ],
+    },
+    status: {
+      type: "string",
+      label: "Status",
+      description: "Status of the incident. Can only be set by operators.",
+      optional: true,
+      options: [
+        "firstLine",
+        "secondLine",
+        "partial",
+      ],
+    },
+    briefDescription: {
+      propDefinition: [
+        app,
+        "briefDescription",
+      ],
+    },
+    request: {
+      propDefinition: [
+        app,
+        "request",
+      ],
+    },
+    action: {
+      propDefinition: [
+        app,
+        "action",
+      ],
+    },
+    actionInvisibleForCaller: {
+      propDefinition: [
+        app,
+        "actionInvisibleForCaller",
+      ],
+    },
+    categoryId: {
+      propDefinition: [
+        app,
+        "categoryId",
+      ],
+    },
+    subcategoryId: {
+      propDefinition: [
+        app,
+        "subcategoryId",
+        ({ categoryId }) => ({
+          categoryId,
+        }),
+      ],
+    },
+    callTypeId: {
+      propDefinition: [
+        app,
+        "callTypeId",
+      ],
+    },
+    entryTypeId: {
+      propDefinition: [
+        app,
+        "entryTypeId",
+      ],
+    },
+    externalNumber: {
+      propDefinition: [
+        app,
+        "externalNumber",
+      ],
+    },
+    objectName: {
+      propDefinition: [
+        app,
+        "objectName",
+      ],
+    },
+    locationId: {
+      propDefinition: [
+        app,
+        "locationId",
+      ],
+    },
+    branchId: {
+      propDefinition: [
+        app,
+        "branchId",
+      ],
+    },
+    mainIncidentId: {
+      type: "string",
+      label: "Main Incident ID",
+      description: "Main incident UUID, required for creating a partial incident. Can only be set by operators.",
+      optional: true,
+    },
+    impact: {
+      propDefinition: [
+        app,
+        "impactId",
+      ],
+    },
+    urgency: {
+      propDefinition: [
+        app,
+        "urgencyId",
+      ],
+    },
+    priority: {
+      propDefinition: [
+        app,
+        "priorityId",
+      ],
+    },
+    duration: {
+      propDefinition: [
+        app,
+        "durationId",
+      ],
+    },
+    targetDate: {
+      propDefinition: [
+        app,
+        "targetDate",
+      ],
+    },
+    slaId: {
+      propDefinition: [
+        app,
+        "slaId",
+      ],
+    },
+    onHold: {
+      propDefinition: [
+        app,
+        "onHold",
+      ],
+    },
+    operatorId: {
+      propDefinition: [
+        app,
+        "operatorId",
+      ],
+      label: "Operator",
+      description: "The operator assigned to the incident. Can only be set by operators.",
+      optional: true,
+    },
+    operatorGroupId: {
+      propDefinition: [
+        app,
+        "operatorGroupId",
+      ],
+    },
+    supplierId: {
+      propDefinition: [
+        app,
+        "supplierId",
+      ],
+    },
+    processingStatusId: {
+      propDefinition: [
+        app,
+        "processingStatusId",
+      ],
+    },
+    responded: {
+      propDefinition: [
+        app,
+        "responded",
+      ],
+    },
+    responseDate: {
+      propDefinition: [
+        app,
+        "responseDate",
+      ],
+    },
+    completed: {
+      propDefinition: [
+        app,
+        "completed",
+      ],
+    },
+    completedDate: {
+      propDefinition: [
+        app,
+        "completedDate",
+      ],
+    },
+    closed: {
+      propDefinition: [
+        app,
+        "closed",
+      ],
+    },
+    closedDate: {
+      propDefinition: [
+        app,
+        "closedDate",
+      ],
+    },
+    closureCodeId: {
+      propDefinition: [
+        app,
+        "closureCodeId",
+      ],
+    },
+    majorCall: {
+      propDefinition: [
+        app,
+        "majorCall",
+      ],
+    },
+    publishToSsd: {
+      propDefinition: [
+        app,
+        "publishToSsd",
+      ],
+    },
+    optionalFields1: {
+      propDefinition: [
+        app,
+        "optionalFields1",
+      ],
+    },
+    optionalFields2: {
+      propDefinition: [
+        app,
+        "optionalFields2",
+      ],
+    },
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+    idempotentHint: false,
+  },
+  async run({ $ }) {
+    const {
+      app,
+      callerLookupId,
+      status,
+      briefDescription,
+      request,
+      action,
+      actionInvisibleForCaller,
+      categoryId,
+      subcategoryId,
+      callTypeId,
+      entryTypeId,
+      externalNumber,
+      objectName,
+      locationId,
+      branchId,
+      mainIncidentId,
+      impact,
+      urgency,
+      priority,
+      duration,
+      targetDate,
+      slaId,
+      onHold,
+      operatorId,
+      operatorGroupId,
+      supplierId,
+      processingStatusId,
+      responded,
+      responseDate,
+      completed,
+      completedDate,
+      closed,
+      closedDate,
+      closureCodeId,
+      majorCall,
+      publishToSsd,
+      optionalFields1,
+      optionalFields2,
+    } = this;
+
+    // Fields that take { id: value } structure
+    const idFields = [
+      {
+        value: callerLookupId,
+        key: "callerLookup",
+      },
+      {
+        value: categoryId,
+        key: "category",
+      },
+      {
+        value: subcategoryId,
+        key: "subcategory",
+      },
+      {
+        value: callTypeId,
+        key: "callType",
+      },
+      {
+        value: entryTypeId,
+        key: "entryType",
+      },
+      {
+        value: locationId,
+        key: "location",
+      },
+      {
+        value: branchId,
+        key: "branch",
+      },
+      {
+        value: mainIncidentId,
+        key: "mainIncident",
+      },
+      {
+        value: impact,
+        key: "impact",
+      },
+      {
+        value: urgency,
+        key: "urgency",
+      },
+      {
+        value: priority,
+        key: "priority",
+      },
+      {
+        value: duration,
+        key: "duration",
+      },
+      {
+        value: slaId,
+        key: "sla",
+      },
+      {
+        value: operatorId,
+        key: "operator",
+      },
+      {
+        value: operatorGroupId,
+        key: "operatorGroup",
+      },
+      {
+        value: supplierId,
+        key: "supplier",
+      },
+      {
+        value: processingStatusId,
+        key: "processingStatus",
+      },
+      {
+        value: closureCodeId,
+        key: "closureCode",
+      },
+    ];
+
+    const response = await app.createIncident({
+      $,
+      data: {
+        status,
+        briefDescription,
+        request,
+        action,
+        actionInvisibleForCaller,
+        externalNumber,
+        targetDate,
+        onHold,
+        responded,
+        responseDate,
+        completed,
+        completedDate,
+        closed,
+        closedDate,
+        majorCall,
+        publishToSsd,
+        optionalFields1,
+        optionalFields2,
+        ...(objectName && {
+          object: {
+            name: objectName,
+          },
+        }),
+        ...idFields.reduce((acc, {
+          value, key,
+        }) => ({
+          ...acc,
+          ...value && {
+            [key]: {
+              id: value,
+            },
+          },
+        }), {}),
+      },
+    });
+
+    $.export("$summary", `Successfully created incident with ID \`${response.id}\``);
+
+    return response;
+  },
+};

package/actions/get-incident/get-incident.mjs

@@ -0,0 +1,39 @@
+import app from "../../topdesk.app.mjs";
+
+export default {
+  key: "topdesk-get-incident",
+  name: "Get Incident",
+  description: "Returns an incident by ID. [See the documentation](https://developers.topdesk.com/explorer/?page=incident#/incident/getIncidentById)",
+  version: "0.0.2",
+  type: "action",
+  props: {
+    app,
+    incidentId: {
+      propDefinition: [
+        app,
+        "incidentId",
+      ],
+    },
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    idempotentHint: true,
+  },
+  async run({ $ }) {
+    const {
+      app,
+      incidentId,
+    } = this;
+
+    const response = await app.getIncident({
+      $,
+      incidentId,
+    });
+
+    $.export("$summary", `Successfully retrieved incident with ID \`${response.id}\``);
+
+    return response;
+  },
+};

package/actions/get-incidents/get-incidents.mjs

@@ -0,0 +1,87 @@
+import app from "../../topdesk.app.mjs";
+
+export default {
+  key: "topdesk-get-incidents",
+  name: "Get Incidents",
+  description: "Returns a list of incidents. [See the documentation](https://developers.topdesk.com/explorer/?page=incident#/incident/getIncidents)",
+  version: "0.0.2",
+  type: "action",
+  props: {
+    app,
+    maxResults: {
+      type: "integer",
+      label: "Max Results",
+      description: "Maximum number of incidents to return. Leave empty to return all incidents.",
+      optional: true,
+    },
+    sort: {
+      type: "string",
+      label: "Sort",
+      description: "The sort order of the returned incidents (e.g., `callDate:asc,creationDate:desc`)",
+      optional: true,
+    },
+    query: {
+      type: "string",
+      label: "Query",
+      description: "A FIQL string to select which incidents should be returned. [See the documentation](https://developers.topdesk.com/tutorial.html#query)",
+      optional: true,
+    },
+    fields: {
+      type: "string",
+      label: "Fields",
+      description: "A comma-separated list of which fields should be returned. By default all fields will be returned.",
+      optional: true,
+    },
+    all: {
+      type: "boolean",
+      label: "All",
+      description: "When set to true, will return all incidents including partials and archived. Otherwise only firstLine and secondLine incidents are returned.",
+      optional: true,
+      default: false,
+    },
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    idempotentHint: true,
+  },
+  async run({ $ }) {
+    const {
+      app,
+      maxResults,
+      sort,
+      query,
+      fields,
+      all,
+    } = this;
+
+    const incidents = [];
+    const paginator = app.paginate({
+      fn: app.listIncidents,
+      fnArgs: {
+        $,
+        params: {
+          sort,
+          query,
+          fields: Array.isArray(fields) && fields?.length
+            ? fields.join(",")
+            : typeof fields === "string" && fields.length
+              ? fields
+              : undefined,
+          all,
+          page_size: 100,
+        },
+      },
+      maxResults,
+    });
+
+    for await (const incident of paginator) {
+      incidents.push(incident);
+    }
+
+    $.export("$summary", `Successfully retrieved \`${incidents.length}\` incident(s)`);
+
+    return incidents;
+  },
+};

package/actions/get-knowledge-item-statuses/get-knowledge-item-statuses.mjs

@@ -0,0 +1,42 @@
+import app from "../../topdesk.app.mjs";
+
+export default {
+  key: "topdesk-get-knowledge-item-statuses",
+  name: "Get Knowledge Item Statuses",
+  description: "Returns the list of possible Knowledge Item statuses. [See the documentation](https://developers.topdesk.com/explorer/?page=knowledge-base#/Searchlists/getStatuses)",
+  version: "0.0.2",
+  type: "action",
+  props: {
+    app,
+    archived: {
+      type: "boolean",
+      label: "Archived",
+      description: "Whether to show archived entries. Leave unset for all entries, or specify true/false for only archived or only active entries, respectively.",
+      optional: true,
+    },
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    idempotentHint: true,
+  },
+  async run({ $ }) {
+    const {
+      app,
+      archived,
+    } = this;
+
+    const response = await app.listKnowledgeItemStatuses({
+      $,
+      params: {
+        archived,
+      },
+    });
+
+    const statusCount = response.results?.length || 0;
+    $.export("$summary", `Successfully retrieved \`${statusCount}\` knowledge item status(es)`);
+
+    return response;
+  },
+};

package/actions/get-knowledge-items/get-knowledge-items.mjs

@@ -0,0 +1,124 @@
+import app from "../../topdesk.app.mjs";
+
+export default {
+  key: "topdesk-get-knowledge-items",
+  name: "Get Knowledge Items",
+  description: "Returns a list of Knowledge Items. [See the documentation](https://developers.topdesk.com/explorer/?page=knowledge-base#/Knowledge%20Items/getKnowledgeItems)",
+  version: "0.0.2",
+  type: "action",
+  props: {
+    app,
+    maxResults: {
+      type: "integer",
+      label: "Max Results",
+      description: "Maximum number of knowledge items to return. Leave empty to return all items.",
+      optional: true,
+    },
+    fields: {
+      type: "string[]",
+      label: "Fields",
+      description: "Additional fields to include in the response. ID and number are always included.",
+      optional: true,
+      options: [
+        "parent",
+        "visibility",
+        "urls",
+        "news",
+        "manager",
+        "status",
+        "standardSolution",
+        "externalLink",
+        "language",
+        "title",
+        "description",
+        "content",
+        "commentsForOperators",
+        "keywords",
+        "creator",
+        "modifier",
+        "creationDate",
+        "modificationDate",
+        "translation.creator",
+        "translation.modifier",
+        "translation.creationDate",
+        "translation.modificationDate",
+        "availableTranslations",
+      ],
+    },
+    query: {
+      type: "string",
+      label: "Query",
+      description: `A FIQL query to filter the response. Use semicolons to combine multiple conditions.
+
+**Available filter fields:**
+- \`parent.id\`, \`parent.number\`
+- \`visibility.sspVisibility\`, \`visibility.sspVisibleFrom\`, \`visibility.sspVisibleUntil\`
+- \`visibility.sspVisibilityFilteredOnBranches\`, \`visibility.operatorVisibilityFilteredOnBranches\`
+- \`visibility.publicKnowledgeItem\`, \`visibility.branches.id\`, \`visibility.branches.name\`
+- \`manager.id\`, \`manager.name\`
+- \`status.id\`, \`status.name\`
+- \`standardSolution.id\`, \`standardSolution.name\`
+- \`externalLink.id\`, \`externalLink.type\`, \`externalLink.date\`
+- \`archived\`, \`news\`
+
+**Operators:**
+- \`==\` (equals), \`!=\` (not equals)
+- \`=gt=\` (greater than), \`=ge=\` (greater than or equal)
+- \`=lt=\` (less than), \`=le=\` (less than or equal)
+- \`=in=\` (in list), \`=out=\` (not in list)
+
+**Example:** \`parent.id==3fa85f64-5717-4562-b3fc-2c963f66afa6;externalLink.id=in=(oneTool,otherTool)\`
+
+[See the documentation](https://developers.topdesk.com/explorer/?page=knowledge-base#/Knowledge%20Items/getKnowledgeItems) for more information.`,
+      optional: true,
+    },
+    language: {
+      type: "string",
+      label: "Language",
+      description: "The language of the Knowledge Item content, in BCP 47 format (e.g., `en`)",
+      optional: true,
+    },
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  async run({ $ }) {
+    const {
+      app,
+      maxResults,
+      fields,
+      query,
+      language,
+    } = this;
+
+    const items = [];
+    const paginator = app.paginate({
+      fn: app.listKnowledgeItems,
+      fnArgs: {
+        $,
+        params: {
+          fields: Array.isArray(fields) && fields?.length
+            ? fields.join(",")
+            : typeof fields === "string" && fields.length
+              ? fields
+              : undefined,
+          query,
+          language,
+          page_size: 100,
+        },
+      },
+      maxResults,
+      dataField: "item",
+    });
+
+    for await (const item of paginator) {
+      items.push(item);
+    }
+
+    $.export("$summary", `Successfully retrieved \`${items.length}\` knowledge item(s)`);
+
+    return items;
+  },
+};