sfEntity
index
/home/sfscript/src/py_sforce/sflib/sfEntity.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.
 
 Python API for sForce 3.0 
   - Customizable wrapper around sfBase3.py classes to create entity specific classes
   - SFEntity class should hold only entity global methods
   - SF<EntityName> should hold methods specific to that entity
   - Branch specific classes
   - Branch/CR workflow methods
   
ToDo:
   - Create many other cool things that cause useful sForce data perturbations.
  
       Chip Vanek (chip@upvia.com), Nov 1st, 2004

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

 
Classes
       
sfBase.SFEntityBase
SFEntity
sfBase.sForceApi3(sop.SFEntitiesMixin, sop.SFUtilityMixin, sop.SFTestMixin)
SFEntityTool

 
class SFEntity(sfBase.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='')
get data list, data is a list of entity-data pairs [('entity', {data})]
multi-entity objects are expected to be a list of these tuples.
- 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 list of entity-data tuple [('entity', {data})]
multi-entity objects are expected to be a list of these tuples.
This overwrite data with the passed in value
showData(self, data=None, entity='', target='console')
display data loaded in this object
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

Data and other attributes defined here:
badInfoList = [None, [], [{}], {}, '', 'fail', 'warn']

Methods inherited from sfBase.SFEntityBase:
showDataFormatError(self, data, entity='')
echo data format error to console

 
class SFEntityTool(sfBase.sForceApi3)
    This class provides entity global capabilities
subclass this class and extend or replace methods to suit your needs
 
 
Method resolution order:
SFEntityTool
sfBase.sForceApi3
sop.SFEntitiesMixin
sop.SFUtilityMixin
sop.SFTestMixin

Methods defined here:
__init__(self, username=None, upass=None, dlog=None, debug=0, logname='sf3.base', setupLog=True)
Creates the API access object and logs in as admin user
create(self, entity, data=[{}], nullEmpty=False)
basic wrapper around create, entity and data is required
ret = {'success':False, 'msg':'', 'errCode':'fail', 'errMsg':'', 'req':'', 'result':[]}
delete(self, ids=[])
basic wrapper around delete
ret = {'success':False, 'msg':'', 'errCode':'fail', 'errMsg':'', 'req':'', 'result':[]}
getActiveCRs(self, daysAgo=5.0)
get all of the CRs modified since daysAgo
getCrById(self, crId)
get all CR Info using the sfId
getCrByNum(self, crNum)
get all CR Info using the CR Number
getCrNumByCrId(self, crId)
get crNum from CR Id
getCrOriginator(self, crInfo)
get the right originator ID for a CR 
- check for admin ID and queues
getCrOriginatorByCrId(self, crId)
resolve the crInfo, call getCrOriginator, then return Originator UserID
getCrOriginatorByCrNum(self, crNum)
resolve the crInfo, call getCrOriginator, then return Originator UserID
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
getEntities(self)
get the latest entitiy list
getEntityMap(self, entity, reset=False)
main accessor for getting entity information
getSOQLEntityShortcut(self, sc)
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]
getUpdated(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':[]}
mailServer(self)
query(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 shortcut strings for common list of return fields (fewer fields is faster!)
- If where is a string it will be passed to getSQOLWhereShortcut(where) to return where clause
- sc will be passed to getSOQLEntityShortcut(sc) to return entity list (and rest of select clause)
    - if sc is empty then all fileds will be returned for entity
 
ret = {'success':False, 'msg':'', 'errCode':'fail', 'errMsg':'', 'req':soql, 'result':[]}
retrieve(self, ids, entity, fieldList='all', allowNulls=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 keys of the returned dictionary (as below)
ret = {'success':False, 'msg':'', 'errCode':'fail', 'errMsg':'', 'req':ids, 'result':[]}
search(self, sterm, retsc=None, scope='ALL FIELDS', sosl=None, limit=200)
search sForce using SOSL >OR< a search term and a return field shortcut
- retsc should be a string passed to getSOSLFieldSpec(retsc) to return formatted return fields
 
results are returned as a keys of the returned dictionary (as below)
ret = {'success':False, 'msg':'', 'errCode':'fail', 'errMsg':'', 'req':ids, 'result':[]}
setupBase(self, setupLog=True)
setup the basic structures need to query the SalesForce API
pass setupLog=False to NOT set up a suite of loggers at this time.
This allows for manually calling setLogger and passing in the loggers
to use.
setupChild(self)
add methods in child classes
showDataUser(self, data=None, entity='')
user console oriented display of data loaded in this object
update(self, entity, data=[{}], nullEmpty=False)
basic wrapper around update, entity and data is required, id must be in data
ret = {'success':False, 'msg':'', 'errCode':'fail', 'errMsg':'', 'req':'', 'result':[]}

Data and other attributes defined here:
badInfoList = [None, [], [{}], {}, '', 'fail', 'warn']
sfAdminIDs = ['']

Methods inherited from sfBase.sForceApi3:
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;/
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
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
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 inherited from sfBase.sForceApi3:
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
       
doCreate(entity, where, parm, options)
doDelete(entity, where, parm, options)
doQuery(entity, where, parm, options)
doSomething(method, term, parm, options)
Command line controlled test of a method
doUpdate(entity, where, parm, options)
getEmpTree(names, options)
just a crude leaf to root tree walker to test getMgrById method
getMgrInfo(uid, last, indent, tool, times=0)
used by getEmpTree
main_CL()
Command line parsing and and defaults methods
showEntities(query, options)
##################################################################################################
#  Logic methods called from command line 
##################################################################################################
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:%S'
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'
badInfoList = [None, [], [{}], {}, '', 'fail', 'warn']
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 'str'>, <type 'unicode'>)]
version = 3.0