salesforce

Sesam-Salesforce connector that can be used to:

• get/delete/upsert objects
• get/delete/upsert valuesets(a.k.a. picklist)
• perform tooling API operations

ENV VARIABLES

CONFIG_NAME	DESCRIPTION	IS_REQUIRED	DEFAULT_VALUE
SF_OBJECTS_CONFIG	dict for object level customizations. see schemas section for description.	no	n/a
LOGIN_CONFIG	a dict either with keys - INSTANCE, CLIENT_ID, CLIENT_SECRET Fex { "CLIENT_ID": "<MY_CLIENT_ID>", "CLIENT_SECRET": "<MY_CLIENT_SECRET>", "INSTANCE": "myinstance.sandbox.my.salesforce.com" } , or - USERNAME, PASSWORD, SECURITY_TOKEN, and optionally DOMAIN(defaults to 'Login' if not set), Fex { "USERNAME": "myusename", "PASSWORD": "mypassword", "SECURITY_TOKEN": "mysecuritytoken", "DOMAIN":"myinstance.sandbox.my" }	yes	n/a
WEBFRAMEWORK	set to 'FLASK' to use flask, otherwise it will run on cherrypy	no	n/a
LOG_LEVEL	LOG_LEVEL. one of [CRITICAL\|ERROR\|WARNING\|INFO\|DEBUG]	no	'INFO'
VALUESET_LIST	a dict where keys are the aliases to be used in sesam and values are the paths to the corresponding valueset. Used when fetching all valusets and for patching. Fex { "my_global_vs": "GlobalValueSet/0Nt5I0000008cw7SAA", "my_custom_vs": "CustomField/00N5I000004yDnkUAE" }	no	n/a
DEFAULT_BULK_SWITCH_THRESHOLD	Integer. Threshold value on the number of incoming entities to swith to bulk-api instead of rest-api.Disabled if not set.	no	None

ENDPOINTS

1. /<datatype>, methods=["GET", "POST", "PUT", "PATCH", "DELETE"]

   By default Id is used to match target object. If Id is not available to Sesam, the SF_OBJECTS_CONFIG envvar can be configured for alternative match keys.

   • "GET": returns all data(upserted and deleted) of type datatype. Response is streamed, thus the response will give 200 status but malformed body when error is encountered.Id and SystemModstamp is set as _id and _updated, respectively.
   • "POST", "PUT", "PATCH": upserts objects or deletes if _deleted is true. Accepts dict or list of dicts.
   • "DELETE": deletes incoming objects.

   query params

   • since: Optional. Data updated after since value will be delivered. CAnnot be older then 30 days ago due to Salesforce REST API limitations.
   • where: Optional. Applicable to GET method condition that will be appended to SOQL select query.
   • extra_attributes: Optional. CSV of extra attributes to fetch. Fex, 'Createdby.name'. N.B. Transit encoding of datetime fields is not supported on these attributes.
   • do_create_if_key_is_empty: Optional. Applicable to POST/PUT/PATCH requests. Allows creation of object when the objectkey cannot be determined.

---

2. /<datatype>/<ext_id_field>/<ext_id>, methods=["GET", "POST", "PUT", "PATCH", "DELETE"]

   Same as point 1, but here the the the objectkey(externalkey here) can additionally be read from the url.

---

3. /<datatype>/<objectkey>, methods=["GET", "POST", "PUT", "PATCH", "DELETE"]

   Same as point 2, but here the the the objectkey(genuine objectkey/Id) can additionally be read from the url.

---

4. /ValueSet, methods=["GET","POST"]

   • "GET": returns all valuesets that are specified in VALUESET_LIST envvar
   • "POST": Upserts values to valuesets. See ValueSet below in schemas section for description of payload.

   Note that a value is disabled via isActive flag in the json.

   query params

   • do_refine: Optional. If equals to one of "0", "false", "no" case-insensitively, the original payload will be returned in data field of the response. Otherwise, only the valueset section.

---

5. /ValueSet/, methods=["GET", "POST"]

   Same as 4. (Sesam required the trailing slach for some reason.)

---

6. /ValueSet/CustomField/<sf_id>, methods=["GET", "POST"]

   Same as 4, but for single valueset that is customfield.

---

7. /ValueSet/GlobalValueSet/<sf_id>, methods=["GET", "POST"]

   Same as 6, but for single valueset that is global valueset.

---

8. /ValueSet/SesamAlias/<alias_in_VALUSET_LIST_envvar>, methods=["GET", "POST"]

   Same as 6, but for single valueset that is global valueset.

---

9. /sf/tooling/<path:path>, methods=["GET", "POST", "DELETE", "PATCH", "PUT"]

   This is endpoint that makes available the Salesforce tooling API.

   query params

   • preserve_as_list: Optional. Applicable to /sf/tooling/path:path requests. If sent as true or 1 and the payload is a list, the first element in the list will be sent forward, othwersie payload is sent forward as it comes in.

---

10. /services/restful/<path:path> or /sf/rest/<path:path>, methods=["GET", "POST", "DELETE", "PATCH", "PUT"]

This is endpoint that makes available any REST call to Salesforce RestAPI. If the original endpoint is `services/data/v{{version}}/mypath1/mypath2/mypath3`, the path in this endpoint should be `/mypath1/mypath2/mypath3`. Query params are passed over.

#### query params     
 * `preserve_as_list`: Optional.  Applicable to /sf/tooling/<path:path> requests. If sent as _true_ or _1_ and the payload is a list, the first element in the list will be sent forward, othwersie payload is sent forward as it comes in. 

---

11. /services/apexrest/<path:path>, methods=["GET", "POST", "DELETE", "PATCH", "PUT"]

This is endpoint that makes available the [apexrest webservices](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_rest.htm). If the original endpoint is `services/apexrest/mypath1/mypath2/mypath3`, the path in this endpoint should be `/mypath1/mypath2/mypath3`. Query params are passed over.

#### query params     
 * `preserve_as_list`: Optional.  Applicable to /sf/tooling/<path:path> requests. If sent as _true_ or _1_ and the payload is a list, the first element in the list will be sent forward, othwersie payload is sent forward as it comes in. 

---

Schema Examples

• SF_OBJECTS_CONFIG is a dict where keysa are sobject names that to be customized. Value is a dict for different customizations available:
  • ordered_key_fields: a ordered list of strings. Effective when setting _id value and Id is not available. The first field that reveals a non-null value will be used to ser _id.

{
        "aadgroup__c": {
            "ordered_key_fields": [
                "sesam_ext_id__c",
                "some_ext_id__c"
            ]
        },
        "Product2":{
            "ordered_key_fields": [
                "sesam_ext_id__c",
                "some_ext_id__c"
            ]
        }
    }

• VALUSET_LIST:

   {
       "alias1": "/GlobalValueSet/0Nt5I0000008cw7SAA",
       "alias2": "/CustomField/00N5I000004yDnkUAE"
   }

• ValueSet:

[
	{
		"data": [
			{
				"color": null,
				"default": false,
				"description": null,
				"isActive": true,
				"label": "mylabel",
				"urls": null,
				"valueName": "myvalue"
			}
		]
	}
]

Example configs:

system:

{
  "_id": "salesforce",
  "type": "system:microservice",
  "metadata": {
    "tags": ["salesforce"]
  },
  "connect_timeout": 60,
  "docker": {
    "environment": {
      "DEFAULT_BULK_SWITCH_THRESHOLD": 999,
      "INSTANCE": "sandbox",
      "LOGIN_CONFIG": "$SECRET(salesforce_login_config)",
      "LOG_LEVEL": "DEBUG",
      "SF_OBJECTS_CONFIG": {
        "Account": {
          "ordered_key_fields": ["myExternalIdFieldForAccount1", "myExternalIdFieldForAccount2", "myExternalIdFieldForAccount3"]
        },
        "Case": {
          "ordered_key_fields": ["myExternalIdFieldFroCaseObject1"]
        }
      }
    },
    "image": "sesamcommunity/salesforce:2.0.0",
    "memory": 8192,
    "port": 5000
  },
  "read_timeout": 7200
}

Input pipe

...
...
...

      "source": {
        "type": "json",
        "system": "salesforce",
        "is_chronological": false,
        "is_since_comparable": true,
        "supports_since": true,
        "url": "/account?extra_attributes=CreatedBy.name&where=IsPersonAccount=false and PersonEmail='myuser@email.com'"
      }
...
...
...