sfBase
index
/home/sfscript/src/py_sforce/sflib/sfBase.py

Copyright 2004 Chip Vanek, Magma Design Automation
 
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
 
      http://www.apache.org/licenses/LICENSE-2.0
 
  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
 
   Base Python API for sForce 3.0 
   - wrapper around ZSI 1.2.8 (from version.py), 1.14,  May 25, 2004 CVS checkout with patches
   - wsdl2python patch to generate right format of proxy classes in SforceService_services
   - Subclass and use the classes in sfEntity.py rather then the methods in this base class
   - Uses persistance classes in sop.py to maintain an automatically updated cache of entity metadata
   
ToDo:
   - Extend old file cache or new sop.py classes to save user based info (username, password, defaults)
   - Add getUpdated & getDeleted support for remote polling of sForce server and local replication
   - Add reset user password support
   - https support to secure login calls and access to sensitive data
   - Add http compression support to improve performance "Accept-Encoding: gzip" & "Content-Encoding:gzip"
   - Add http Persistent Connection to improve performance and response time
   - Add retry support to recove from network or load based errors (rate limit, socket errors, unavailable)
 
          Chip Vanek (chip@upvia.com), Nov 1st, 2004

 
Modules
       
StringIO
ZSI
base64
copy
getopt
logging
os
pprint
re
SforceService_services
sys
time
traceback
urlparse

 
Classes
       
sop.SFEntitiesMixin
sForceApi3(sop.SFEntitiesMixin, sop.SFUtilityMixin, sop.SFTestMixin)
SFEntityBase
sop.SFTestMixin
sForceApi3(sop.SFEntitiesMixin, sop.SFUtilityMixin, sop.SFTestMixin)
sop.SFUtilityMixin
sForceApi3(sop.SFEntitiesMixin, sop.SFUtilityMixin, sop.SFTestMixin)

 
class SFEntityBase
    Simple base class that is aware of an active sForce connection but
does not implement all of the connection oriented and data management APIs
 
Subclass this object to create entity specific data management and business
logic methods.
 
  Methods defined here:
__init__(self, entity, data={'': {}}, action=None, sfTool=None, debug=0)
If an active tool object is not passed in then a connection is created.
getData(self, entity='all', id='')
return the data 
- list of data dictionaries if just entity provided
- specific data dictionary if id is in entity list
setAction(self, action)
set action with any object specific triggered actions
setData(self, data, reset=False)
set data with any object specific filtering  
data is a dictionary of entity-data pairs {'entity': {data}}
multi-value entities a list of data elements {'entity',[{data}]}
multi-entity objects are expected to have multiple entity keys.
showDataFormatError(self, data, entity='')
echo data format error to console
updateSF(self, data=None, nullEmpty=False)
Update sForce with all the data in this object
This data may update multiple entities in sForce and may null fields
ToDo: update all similar entities in the same call

 
class sForceApi3(sop.SFEntitiesMixin, sop.SFUtilityMixin, sop.SFTestMixin)
    This class provides basic sForce API capabilities
 
 
Method resolution order:
sForceApi3
sop.SFEntitiesMixin
sop.SFUtilityMixin
sop.SFTestMixin

Methods defined here:
__init__(self, username=None, upass=None, dlog=None, debug=0, logname='sf3.base')
Creates the API access object and logs in as admin user
Use the client 'cookie' from first API, $HOME/.sfdcLogin
checkDate(self, dt, where='')
check format of date string and return secs or return ''
checkResults(self, method, resp, ret, entity, data)
common parsing of the receive object with error checks
cmpIds(self, idOne, idTwo)
many but not all sForce ID are returned in the API as 18 character
createBase(self, entity, data=[{}], nullEmpty=False)
basic wrapper around create, entity and data is required
useAdm is a flag which, if true, uses the admin login to execute
the call.
delCache(self, key)
delete specific cache value
deleteBase(self, ids=[])
basic wrapper around delete
getAsDateTimeStr(self, value, offset=0)
return time as 2004-01-10T00:13:50.000Z
getCache(self, key, data={}, reset=False)
main accessor for getting cache information
getConfig(self)
getConnectInfo(self, version='3.0', startTime=None)
return connection information
getDataOFF(self, entity='all', id='')
return the data 
- list of data dictionaries if just entity provided
- specific data dictionary if id is in entity list
getDateTimeTuple(self, value, offset=0)
return time tuple for any input, yet right;/
getDefaults(self, uid='', entity='all')
return a dictionary of default field values that can be used by any entity
UserID and entity specific dictionaries is not implemented yet but should be
getDisplayDateTime(self, value)
return a command line displayable Date Time string 
typical input -> 2004-01-10T00:13:50.000Z
output <- June 31, 2004 2:00pm PST
getEntities(self)
get the latest entitiy list
getEntityMap(self, entity, reset=False)
main accessor for getting entity information
getId15(self, id)
Return the 15 char version of the id
getId18(self, id)
Return the 18 char version of the id
getOldPwFile(self)
get the username and password out of the old .sfdcLogin file
getSOQLEntityShortcut(self, sc, entity='Case')
Convert a shortcut string into a valid SOQL string
format: SELECT fieldList from objectType
getSOSLFieldSpec(self, shortcut)
Convert a shortcut string into a valid SOSL FieldSpec string
getSQOLWhereShortcut(self, sc='')
convert some shortcut strings into valid WHERE clause
Output is a a list of clause triplets and operators [and, or, not]
getSessionHeader(self)
getTime(self, value=None)
format the time string, used in walkSCM
getUpdatedBase(self, entity, start=None, end=None)
return data dictionaries for all entity items modified between the start and end times
Provide start and end time as DateTime object or sec since epoch or string as #####
results are returned as a list in the results key of the returned dictionary (as below)
ret = {'success':False, 'msg':'', 'errCode':'fail', 'errMsg':'', 'req':ids, 'result':[]}
getUserAuth(self, type='user', userPwd=None)
get the user authentication credentials from their config file or set them
getUserIdByUsername(self, email)
getUserInfo(self)
get the information of the current logged in user
loadSendObj(self, req, entity, dataList=[{}], nullEmpty=False, default={}, create=False)
basic wrapper around the loading of the ZSI proxy object by updating the ofWhat attribute on the typecode object
Makes us of the sop entityMap loaded with entity and filed constraints.  A number of basic type constraines are supported
used by create and update
Provide:
   req    = default request object for create or update call
   entity = type of sForce entiy to query entityMap, all data MUST be same entity type
   data   = dictionary with all field values (ID is required)
   nullEmpty = True|False to indicate if fields not in data will be deleted on server
   default = dictionary of fields and values that will be used for any matching empty fields in data
              (still do not know how to handle combo of nullEmpty and default, will return later)
Returns results dictionary with:
   success = True|False
   errCode = warn|data|field|fail - Fail will not allow object to be used others eliminate offending info from object
   errMsg  = text version of what is not right
   req     = request object with updated sObject list, ofWhat list and field data set on sObjects
loginSF(self, user=None, adminpw=['', ''])
login to the sForce API server
makeDateTime(self, value)
make into a standard Date Time string from GMT
queryBase(self, entity, where=[('LastName', 'like', 'vanek')], sc='', soql=None, limit=200)
search sForce using SOQL with some query building shortcuts
using entity name and a set of shorcut strings for common list of return fields (fewer fields is faster!)
CV June 1, 2004 Need to review error handling
retrieveBase(self, ids, entity, fieldList=[], allowNulls=False, asAdm=False)
return data dictionaries for list of ids, used allowNulls to return empty values
Provide list of ids along with a list of fields you want back
results are returned as a list in the results key of the returned dictionary (as below)
searchBase(self, sterm, retsc=None, scope='ALL FIELDS', sosl=None, limit=200)
search sForce using SOSL
FIND {sterm} IN 'ALL FIELDS|NAME FIELDS|EMAIL FIELDS|PHONE FIELDS'
RETURNING 'FieldSpec' LIMIT #
eg: Find {MyProspect} RETURNING CustomObject_c(id, CustomField_c)
CV June 1, 2004 Need to review error handling
setCache(self, key, data={})
load the latest data for the key into a simple object persitence dictionary
setData(self, data, reset=False)
simple set data as a dictionary of entity-data pairs {'entity': [{data}]}
multi-entity objects are expected to have multiple entity keys.
setDefaultLoggers(self, name='sf')
setup a default reusable logger reference if no logger.ini
file is found
setLog(self, msg, type='info')
log critical errors
setLogger(self, name=None, note=None, logger=None, dlogger=None, elogger=None, clogger=None)
setup a reusable logger reference
setUserAuth(self, type='user', userPwd=None)
Prompt the user for their password and store it in their configuration file
showData(self, data=None, entity='', target='console')
display data loaded in this object
showDataConsole(self, data=None, entity='')
console oriented display of data loaded in this object
showDataFormatError(self, data, entity='')
echo data format error to console
showDictConsole(self, data=None)
console oriented display of data dictionary
showDictConsole2(self, data=None)
console oriented display of data dictionary
updateBase(self, entity, data=[{}], nullEmpty=False)
basic wrapper around update, entity and data is required, id must be in data

Data and other attributes defined here:
data = {}
em = {}
entity = ''
entityTS = 0
home = 'sfscript'

Methods inherited from sop.SFEntitiesMixin:
describeGlobal(self)
describe global and set available entity list on object describeGlobal
describeSObject(self, sObjectType)
describe objects
getEntityMapFromSF(self, ent)
query sForce on metasdata on entity and return as a dictionary
_activateable: boolean
_createable: boolean
_custom: boolean
_deletable: boolean
_fields: ns2.Field_Def, optional
  _label: str
  _name: str
  _nameField: boolean
  _custom: boolean
  _filterable: boolean          -  us in where clause
  _nillable: boolean
  _createable: boolean
  _updateable: boolean
  _referenceTo: str, optional
 
  _restrictedPicklist: boolean
  _picklistValues: ns2.PicklistEntry_Def, optional
    _active: boolean
    _defaultValue: boolean
    _label: str, optional
    _value: str
  _byteLength: int
  _length: int
  _digits: int
  _precision: int
  _scale: int
  _soapType: ns2.soapType_Def
    _soapType: str, optional
  _type: ns2.fieldType_Def
    _fieldType: str, optional
_label: str
_name: str
_queryable: boolean
_replicateable: boolean
_retrieveable: boolean
_searchable: boolean
_undeletable: boolean
_updateable: boolean
setEntitiesMap(self)
load the latest metadata into a simple object persitence dictionary
setEntityMap(self, entity)
load the latest metadata for entity into a simple object persitence dictionary

Methods inherited from sop.SFUtilityMixin:
baseconvert(number, fromdigits, todigits)
convertChunk(chunk)
Used by convertId15ToId18
convertId15ToId18(id15)
Convert sForce 15 character IDs to 18 char IDs

Data and other attributes inherited from sop.SFUtilityMixin:
BASE10 = '0123456789'
BASE16 = '0123456789ABCDEF'
BASE2 = '01'
BASE8 = '01234567'
BINARY = '01'
DECIMAL = '0123456789'
HEX = '0123456789ABCDEF'
OCTAL = '01234567'
TRANSLATION_TABLE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345'

Methods inherited from sop.SFTestMixin:
createTest1(self, entity='Task', data={}, nullEmpty=False, seed='on seed')
Some test data around the create call
getBySOQLBad(self, soql=None, limit=200)
search sForce using SOQL, return objects using retrieve call
CV May 25, 2004, another dead end with the state of the proxy objects
getRecType(self, node)
this assumes a DOM node object, Just used in getZSIProxyClass, so trash during cleanup
getZSIProxyClass(self, records)
Not used now, was a thread towards using the proxy objects build by wsdl2python
New way is to use the sellf.getEntityMap('entity') dictionary cached in file pickle
CV May 25, 2004, another dead end with the state of the proxy objects
retrieveByIds(self, ids=[], entity='Contact')
try the ZSI Proxy type objects, 
CV May 25, 2004, another dead end with the state of the proxy objects
updateTest1(self, entity='Task', data={}, nullEmpty=False, seed='on seed')
Some test data around the update call

 
Functions
       
doTestMethods(method, term, parm, options)
update SF using passed data
genApiFiles(options)
output the API files
main_CL()
Command line parsing and and defaults methods
openTraceFile(fname)
open next available file name
testMethods(method, term, options)
update SF using passed data
usage(err='')
Prints the Usage() statement for the program

 
Data
        ACCOUNT_OBJ = 'Account'
ACCOUNT_SIG = '001'
BAD_INFO_LIST = [None, [], [{}], {}, '', 'fail', 'warn']
BRANCH_CR_LINK_OBJ = 'Branch_CR_Link__c'
CASE_OBJ = 'Case'
CASE_SIG = '500'
CONTACT_OBJ = 'Contact'
CONTACT_SIG = '003'
ISO_8601_DATETIME = '%Y-%m-%dT%H:%M:%SZ'
LEAD_OBJ = 'Lead'
LEAD_OWNER_SIG = ['005', '00G']
LEAD_SIG = '00Q'
NOTE_OBJ = 'Note'
NOTE_SIG = '002'
QUEUE_OBJ = 'Queue'
QUEUE_SIG = '00G'
RECTYPE_CR = '01230000000001YAAQ'
RECTYPE_PVCR = '0123000000003qfAAA'
StringTypes = (<type 'str'>, <type 'unicode'>)
TASK_BRANCH_OBJ = 'Task_Branch__c'
TEAM_BRANCH_OBJ = 'Team_Branch__c'
USER_OBJ = 'User'
USER_SIG = '005'
dictTypes = [<type 'dict'>, <type 'dict'>]
numTypes = (<type 'long'>, <type 'float'>)
seqTypes = [<type 'list'>, <type 'tuple'>]
sfCache = <sop.AccessFactory instance>
sfEntities = <sop.AccessFactory instance>
strTypes = [<type 'str'>, <type 'unicode'>]
version = 3.0