@pipedream/salesforce_rest_api 1.2.1 → 1.3.0

package/README.md

@@ -1,3 +1,7 @@
+# Overview
+
+The Salesforce (REST API) provides a powerful platform for creating and managing customer relationships with a wide array of features like data manipulation, querying, and complex automation. With Pipedream's serverless execution, you can create workflows that automate your sales processes, sync data with other platforms, enhance customer engagement, and trigger actions based on specific events. Dive into Salesforce data, streamline lead management, track customer interactions, and push or pull data to or from Salesforce seamlessly.
+
 # Getting Started
 
 You can install the Pipedream Salesforce app in the [Accounts](https://pipedream.com/accounts) section of your Pipedream account, or directly in a workflow.
@@ -65,6 +69,24 @@ If you'd like to utilize Pipedream's webhook triggers, you will need to add the
 
 11. You should now be able to use the Salesforce integration along with the webhook triggers if you configured the required permissions above.
 
+# Example Use Cases
+
+## **Synchronization between Salesforce and External Databases**
+
+Synchronize Salesforce with external databases to ensure data accuracy and consistency without manual effort.
+
+## **Real-Time Customer Support Notifications**
+
+Improve customer service responsiveness by triggering real-time notifications to support teams when new tickets are created.
+
+## **Lead Scoring and Engagement Automation**
+
+Streamline lead management by automatically scoring and engaging leads through personalized campaigns, enhancing conversion rates.
+
+## **Dynamic Inventory Management**
+
+Keep inventory levels accurate and responsive to sales activity by updating Salesforce in real-time based on e-commerce data.
+
 
 # Troubleshooting
 
@@ -103,3 +125,73 @@ If you happen to stumble on the error: `UNKNOWN_EXCEPTION: admin operation alrea
 15. Back to the Pipedream Workflow, create a new step with the **Salesforce Convert SOAP Object** action.
 16. In the **XML Soap Object** field, select the path from the trigger or type in `{{steps.trigger.event.body}}`.
 17. That's it! You can now deploy the workflow and you will receive instant updates from Salesforce.
+
+## API Errors
+
+Below is a list of potential HTTP response status codes with their corresponding causes:
+
+### **400**
+
+The request couldn't be understood, usually because the JSON or XML body contains an error.
+
+### **401**
+
+The session ID or OAuth token used has expired or is invalid. The response body contains the message and errorCode.
+
+### **403**
+
+The request has been refused. Check that the logged-in user has appropriate permissions. If the error code is REQUEST_LIMIT_EXCEEDED, the API request limits in your org have been exceeded.
+
+### **404**
+
+The requested resource couldn't be found. Check the URI for errors, and ensure there are no sharing issues.
+
+### **405**
+
+The method specified isn’t allowed for the resource indicated in the URI.
+
+### **409**
+
+The request couldn’t be completed due to a conflict with the current state of the resource. Ensure the API version is compatible with the resource requested.
+
+### **410**
+
+The requested resource has been retired or removed. Update or delete references to the resource.
+
+### **412**
+
+The request wasn't executed because it didn't meet one or more preconditions specified in the request headers.
+
+
+### **414**
+
+The length of the URI exceeds the 16,384-byte limit.
+
+### **415**
+
+The entity in the request is in a format that's not supported by the specified method.
+
+### **420**
+
+Salesforce Edge doesn’t have routing information for the request host. Contact Salesforce Customer Support.
+
+### **428**
+
+The request wasn’t executed because it wasn't conditional. Add a Conditional Request Header like If-Match to the request.
+
+### **431**
+
+The combined length of the URI and headers exceeds the 16,384-byte limit.
+
+### **500**
+
+An error within Lightning Platform has occurred, preventing request completion. Contact Salesforce Customer Support.
+
+### **502**
+
+Salesforce Edge couldn’t communicate successfully with the Salesforce instance.
+
+### **503**
+
+The server is currently unable to handle the request, typically due to maintenance or being overloaded.
+

package/actions/add-contact-to-campaign/add-contact-to-campaign.mjs

@@ -1,52 +1,52 @@
-import salesForceRestApi from "../../salesforce_rest_api.app.mjs";
-import {
-  removeNullEntries, toSingleLineString,
-} from "../../common/utils.mjs";
+import salesforce from "../../salesforce_rest_api.app.mjs";
 import constants from "../../common/constants.mjs";
 
 export default {
   key: "salesforce_rest_api-add-contact-to-campaign",
   name: "Add Contact to Campaign",
-  description: toSingleLineString(`
-    Adds an existing contact to an existing campaign.
-    See [Event SObject](https://developer.salesforce.com/docs/atlas.en-us.228.0.object_reference.meta/object_reference/sforce_api_objects_campaignmember.htm)
-    and [Create Record](https://developer.salesforce.com/docs/atlas.en-us.228.0.api_rest.meta/api_rest/dome_sobject_create.htm)
-  `),
-  version: "0.0.6",
+  description: "Adds an existing contact to an existing campaign. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.228.0.object_reference.meta/object_reference/sforce_api_objects_campaignmember.htm)",
+  version: "0.1.0",
   type: "action",
   props: {
-    salesForceRestApi,
+    salesforce,
     campaignId: {
       propDefinition: [
-        salesForceRestApi,
-        "sobjectId",
+        salesforce,
+        "recordId",
         () => ({
-          objectType: constants.OBJECT_TYPE.CAMPAIGN,
+          objType: "Campaign",
+          nameField: "Name",
         }),
       ],
       label: "Campaign ID",
-      description: "ID of the Campaign to which this Lead is associated.",
+      description: "The Campaign to add a Contact to.",
     },
     contactId: {
       propDefinition: [
-        salesForceRestApi,
-        "sobjectId",
+        salesforce,
+        "recordId",
         () => ({
-          objectType: constants.OBJECT_TYPE.CONTACT,
+          objType: "Contact",
+          nameField: "Name",
         }),
       ],
       label: "Contact ID",
-      description: "ID of the Contact who is associated with a Campaign.",
+      description: "The Contact to add to the selected Campaign.",
     },
   },
   async run({ $ }) {
-    const data = removeNullEntries({
-      CampaignId: this.campaignId,
-      ContactId: this.contactId,
+    const {
+      salesforce, campaignId, contactId,
+    } = this;
+    const response = await salesforce.createObject({
+      $,
+      objectType: constants.OBJECT_TYPE.CAMPAIGN_MEMBER,
+      data: {
+        CampaignId: campaignId,
+        ContactId: contactId,
+      },
     });
-    const response = await this.salesForceRestApi
-      .createObject(constants.OBJECT_TYPE.CAMPAIGN_MEMBER, data);
-    response && $.export("$summary", "Successfully added contact to campaign");
+    $.export("$summary", `Successfully added contact (ID: ${contactId}) to campaign (ID: ${campaignId})`);
     return response;
   },
 };

package/actions/add-lead-to-campaign/add-lead-to-campaign.mjs

@@ -1,51 +1,52 @@
-import salesForceRestApi from "../../salesforce_rest_api.app.mjs";
-import {
-  removeNullEntries, toSingleLineString,
-} from "../../common/utils.mjs";
+import salesforce from "../../salesforce_rest_api.app.mjs";
 import constants from "../../common/constants.mjs";
 
 export default {
   key: "salesforce_rest_api-add-lead-to-campaign",
   name: "Add Lead to Campaign",
-  description: toSingleLineString(`
-    Adds an existing lead to an existing campaign.
-    See [Event SObject](https://developer.salesforce.com/docs/atlas.en-us.228.0.object_reference.meta/object_reference/sforce_api_objects_campaignmember.htm)
-    and [Create Record](https://developer.salesforce.com/docs/atlas.en-us.228.0.api_rest.meta/api_rest/dome_sobject_create.htm)
-  `),
-  version: "0.0.6",
+  description: "Adds an existing lead to an existing campaign. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.228.0.object_reference.meta/object_reference/sforce_api_objects_campaignmember.htm)",
+  version: "0.1.0",
   type: "action",
   props: {
-    salesForceRestApi,
+    salesforce,
     campaignId: {
       propDefinition: [
-        salesForceRestApi,
-        "sobjectId",
+        salesforce,
+        "recordId",
         () => ({
-          objectType: constants.OBJECT_TYPE.CAMPAIGN,
+          objType: "Campaign",
+          nameField: "Name",
         }),
       ],
       label: "Campaign ID",
-      description: "ID of the Campaign to which this Lead is associated.",
+      description: "The Campaign to add a Lead to.",
     },
     leadId: {
       propDefinition: [
-        salesForceRestApi,
-        "sobjectId",
+        salesforce,
+        "recordId",
         () => ({
-          objectType: constants.OBJECT_TYPE.LEAD,
+          objType: "Lead",
+          nameField: "Name",
         }),
       ],
       label: "Lead ID",
-      description: "ID of the Lead who is associated with a Campaign.",
+      description: "The Lead to add to the selected Campaign.",
     },
   },
   async run({ $ }) {
-    const data = removeNullEntries({
-      CampaignId: this.campaignId,
-      LeadId: this.leadId,
+    const {
+      salesforce, campaignId, leadId,
+    } = this;
+    const response = await salesforce.createObject({
+      $,
+      objectType: constants.OBJECT_TYPE.CAMPAIGN_MEMBER,
+      data: {
+        CampaignId: campaignId,
+        LeadId: leadId,
+      },
     });
-    const response = await this.salesForceRestApi.createObject("CampaignMember", data);
-    response && $.export("$summary", "Successfully added lead to campaign");
+    $.export("$summary", `Successfully added lead (ID: ${leadId}) to campaign (ID: ${campaignId})`);
     return response;
   },
 };

package/actions/common/base-create-update.mjs

@@ -0,0 +1,108 @@
+import { ConfigurationError } from "@pipedream/platform";
+import salesforce from "../../salesforce_rest_api.app.mjs";
+import { getAdditionalFields } from "../../common/props-utils.mjs";
+
+export const additionalFields = {
+  type: "object",
+  label: "Additional Fields",
+  description:
+      "Other fields to set for this record. Values will be parsed as JSON where applicable.",
+  optional: true,
+};
+
+export function getProps({
+  objType,
+  createOrUpdate = "create",
+  docsLink = "https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_concepts.htm",
+  showDateInfo = false,
+}) {
+  let { initialProps } = objType;
+  if (initialProps && createOrUpdate === "update") {
+    initialProps = Object.fromEntries(
+      Object.entries(initialProps).map(([
+        key,
+        value,
+      ]) => [
+        key,
+        {
+          ...value,
+          optional: true,
+        },
+      ]),
+    );
+  }
+
+  return {
+    salesforce,
+    ...showDateInfo && {
+      dateInfo: {
+        type: "alert",
+        alertType: "warning",
+        content: "Date fields should be a [valid date string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format) or a Unix timestamp in milliseconds. Example values: `2022-01-15T18:30:00.000Z` or `1642271400000`.",
+      },
+    },
+    ...objType[createOrUpdate === "create"
+      ? "createProps"
+      : "updateProps"],
+    ...initialProps,
+    docsInfo: {
+      type: "alert",
+      alertType: "info",
+      content: `[See the documentation](${docsLink}) for more information on available fields.`,
+    },
+    useAdvancedProps: {
+      propDefinition: [
+        salesforce,
+        "useAdvancedProps",
+      ],
+    },
+  };
+}
+
+export default {
+  methods: {
+    getObjectType() {
+      return "";
+    },
+    getAdvancedProps() {
+      return {};
+    },
+    getAdditionalFields,
+    formatDateTimeProps(props = {}) {
+      // https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_valid_date_formats.htm
+      return Object.fromEntries(Object.entries(props).filter(([
+        , value,
+      ]) => value !== undefined)
+        .map(([
+          key,
+          value,
+        ]) => {
+          const numValue = Number(value);
+          const date = new Date(Number.isNaN(numValue)
+            ? value
+            : numValue);
+          if (Number.isNaN(date.valueOf())) {
+            throw new ConfigurationError(`Invalid date format for prop \`${key}\`. Please provide a valid date format.`);
+          }
+          return [
+            key,
+            date.toISOString(),
+          ];
+        }));
+    },
+  },
+  async additionalProps() {
+    const objectType = this.getObjectType();
+    if (!this.useAdvancedProps || !objectType) return {};
+
+    const fields = (await this.salesforce.getFieldsForObjectType(objectType));
+    const fieldNames = fields.map((f) => f.name);
+    const filteredProps = Object.fromEntries(Object.entries(this.getAdvancedProps()).filter(([
+      key,
+    ]) => fieldNames.includes(key) || key[0] === key[0].toLowerCase()));
+    return {
+      ...filteredProps,
+      additionalFields,
+    };
+  },
+};

package/actions/convert-soap-xml-to-json/convert-soap-xml-to-json.mjs

@@ -5,10 +5,17 @@ export default {
   key: "salesforce_rest_api-convert-soap-xml-to-json",
   name: "Convert SOAP XML Object to JSON",
   description: "Converts a SOAP XML Object received from Salesforce to JSON",
-  version: "0.0.5",
+  version: "0.0.6",
   type: "action",
   props: {
     salesforce_rest_api,
+    infoBox: {
+      type: "alert",
+      alertType: "info",
+      content: `This action is useful in conjunction with Salesforce Flow Builder, and is primarily used if Instant triggers are not working for your use case.
+\\
+[See the documentation](https://pipedream.com/apps/salesforce-rest-api#troubleshooting) for more details.`,
+    },
     xml: {
       type: "string",
       label: "XML Soap Object",
@@ -17,14 +24,14 @@ export default {
     extractNotificationOnly: {
       type: "boolean",
       label: "Extract Notifications Only",
-      description: "Extracts only the notification parts from the XML. Default: `true`.",
+      description: "Whether to extract only the notification parts from the XML. Default: `true`.",
       optional: true,
       default: true,
     },
     failOnError: {
       type: "boolean",
       label: "Fail on Error",
-      description: "If should fail on error when extracting notifications. Default: `false`.",
+      description: "Whether the action should fail if an error occurs when extracting notifications. Default: `false`.",
       optional: true,
       default: false,
     },
@@ -44,6 +51,7 @@ export default {
     try {
       const notifications = json.elements[0].elements[0].elements[0].elements
         .filter(({ name }) => name === "Notification");
+      $.export("$summary", "Successfully converted to JSON and extracted notifications");
       return {
         notifications,
       };

package/actions/create-account/create-account.mjs

@@ -1,52 +1,49 @@
-import common from "../common/base.mjs";
+import common, { getProps } from "../common/base-create-update.mjs";
 import account from "../../common/sobjects/account.mjs";
-import {
-  pickBy, pick,
-} from "lodash-es";
-import { toSingleLineString } from "../../common/utils.mjs";
 
-const { salesforce } = common.props;
+export const docsLink = "https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_account.htm";
 
 export default {
   ...common,
   key: "salesforce_rest_api-create-account",
   name: "Create Account",
-  description: toSingleLineString(`
-    Creates a Salesforce account, representing an individual account,
-    which is an organization or person involved with your business (such as customers, competitors, and partners).
-    See [Account SObject](https://developer.salesforce.com/docs/atlas.en-us.228.0.object_reference.meta/object_reference/sforce_api_objects_account.htm)
-    and [Create Record](https://developer.salesforce.com/docs/atlas.en-us.228.0.api_rest.meta/api_rest/dome_sobject_create.htm)
-  `),
-  version: "0.2.7",
+  description: `Creates a Salesforce account. [See the documentation](${docsLink})`,
+  version: "0.3.0",
   type: "action",
-  props: {
-    salesforce,
-    Name: {
-      type: "string",
-      label: "Name",
-      description: "Name of the account.",
+  methods: {
+    ...common.methods,
+    getObjectType() {
+      return "Account";
     },
-    selector: {
-      propDefinition: [
-        salesforce,
-        "fieldSelector",
-      ],
-      description: `${salesforce.propDefinitions.fieldSelector.description} Account`,
-      options: () => Object.keys(account),
-      reloadProps: true,
+    getAdvancedProps() {
+      return account.extraProps;
     },
   },
-  additionalProps() {
-    return this.additionalProps(this.selector, account);
-  },
+  props: getProps({
+    objType: account,
+    docsLink,
+  }),
   async run({ $ }) {
-    const data = pickBy(pick(this, [
-      "Name",
-      ...this.selector,
-    ]));
-    const response = await this.salesforce.createAccount({
+    /* eslint-disable no-unused-vars */
+    const {
+      salesforce,
+      getAdvancedProps,
+      getObjectType,
+      getAdditionalFields,
+      formatDateTimeProps,
+      useAdvancedProps,
+      docsInfo,
+      dateInfo,
+      additionalFields,
+      ...data
+    } = this;
+    /* eslint-enable no-unused-vars */
+    const response = await salesforce.createRecord("Account", {
       $,
-      data,
+      data: {
+        ...data,
+        ...getAdditionalFields(),
+      },
     });
     $.export("$summary", `Successfully created account "${this.Name}"`);
     return response;

package/actions/create-attachment/create-attachment.mjs

@@ -1,63 +1,49 @@
-import common from "../common/base.mjs";
+import common, { getProps } from "../common/base-create-update.mjs";
 import attachment from "../../common/sobjects/attachment.mjs";
-import {
-  pickBy, pick,
-} from "lodash-es";
-import { toSingleLineString } from "../../common/utils.mjs";
+import fs from "fs";
 
-const { salesforce } = common.props;
+const docsLink = "https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_attachment.htm";
+
+/* eslint-disable no-unused-vars */
+const {
+  useAdvancedProps, ...props
+} = getProps({
+  objType: attachment,
+  docsLink,
+});
+/* eslint-enable no-unused-vars */
 
 export default {
   ...common,
   key: "salesforce_rest_api-create-attachment",
   name: "Create Attachment",
-  description: toSingleLineString(`
-    Creates an attachment, which represents a file that a User has uploaded and attached to a parent object.
-    See [Attachment SObject](https://developer.salesforce.com/docs/atlas.en-us.228.0.object_reference.meta/object_reference/sforce_api_objects_attachment.htm)
-    and [Create Record](https://developer.salesforce.com/docs/atlas.en-us.228.0.api_rest.meta/api_rest/dome_sobject_create.htm)
-  `),
-  version: "0.3.7",
+  description: `Creates an Attachment on a parent object. [See the documentation](${docsLink})`,
+  version: "0.4.0",
   type: "action",
-  props: {
-    salesforce,
-    Body: {
-      type: "string",
-      label: "Body",
-      description: "Encoded file data.",
-    },
-    Name: {
-      type: "string",
-      label: "Name",
-      description: "Name of the attached file. Maximum size is 255 characters.",
-    },
-    ParentId: {
-      type: "string",
-      label: "Parent ID",
-      description: "ID of the parent object of the attachment. The following objects are supported as parents of attachments:\n* Account\n* Asset\n* Campaign\n* Case\n* Contact\n* Contract\n* Custom objects\n* EmailMessage\n* EmailTemplate\n* Event\n* Lead\n* Opportunity\n* Product2\n* Solution\n* Task",
-    },
-    selector: {
-      propDefinition: [
-        salesforce,
-        "fieldSelector",
-      ],
-      description: `${salesforce.propDefinitions.fieldSelector.description} Attachment`,
-      options: () => Object.keys(attachment),
-      reloadProps: true,
-    },
-  },
-  additionalProps() {
-    return this.additionalProps(this.selector, attachment);
-  },
+  props,
   async run({ $ }) {
-    const data = pickBy(pick(this, [
-      "Body",
-      "Name",
-      "ParentId",
-      ...this.selector,
-    ]));
-    const response = await this.salesforce.createAttachment({
+    /* eslint-disable no-unused-vars */
+    const {
+      salesforce,
+      getAdvancedProps,
+      getAdditionalFields,
+      formatDateTimeProps,
+      docsInfo,
+      filePathOrContent,
+      ...data
+    } = this;
+    /* eslint-enable no-unused-vars */
+
+    const body =  filePathOrContent.includes("tmp/")
+      ? (await fs.promises.readFile(filePathOrContent)).toString("base64")
+      : filePathOrContent;
+
+    const response = await salesforce.createRecord("Attachment", {
       $,
-      data,
+      data: {
+        Body: body,
+        ...data,
+      },
     });
     $.export("$summary", `Successfully created attachment "${this.Name}"`);
     return response;