docs: def add_pending_job(job_id, job_key, job_type, api_key,
                      data=None, metadata=None, result_url=None):
      """Add a new job with status "pending" to the jobs table.
  
      All code that adds jobs to the jobs table should go through this function.
      Code that adds to the jobs table manually should be refactored to use this
      function.
  
      May raise unspecified exceptions from Python core, SQLAlchemy or JSON!
      TODO: Document and unit test these!
  
      :param job_id: a unique identifier for the job, used as the primary key in
          ckanserviceprovider's "jobs" database table
      :type job_id: unicode
  
      :param job_key: the key required to administer the job via the API
      :type job_key: unicode
  
      :param job_type: the name of the job function that will be executed for
          this job
      :type job_key: unicode
  
      :param api_key: the client site API key that ckanserviceprovider will use
          when posting the job result to the result_url
      :type api_key: unicode
  
      :param data: The input data for the job (called sent_data elsewhere)
      :type data: Any JSON-serializable type
  
      :param metadata: A dict of arbitrary (key, value) metadata pairs to be
          stored along with the job. The keys should be strings, the values can
          be strings or any JSON-encodable type.
      :type metadata: dict
  
      :param result_url: the callback URL that ckanserviceprovider will post the
          job result to when the job has finished
      :type result_url: unicode
  
      """
      if not data:
          data = {}
      data = json.dumps(data)
  
      # Turn strings into unicode to stop SQLAlchemy
      # "Unicode type received non-unicode bind param value" warnings.
      if job_id:
          job_id = unicode(job_id)
      if job_type:
          job_type = unicode(job_type)
      if result_url:
          result_url = unicode(result_url)
      if api_key:
          api_key = unicode(api_key)
      if job_key:
          job_key = unicode(job_key)
      data = unicode(data)
  
      if not metadata:
          metadata = {}
  
      conn = ENGINE.connect()
      trans = conn.begin()
      try:
          conn.execute(JOBS_TABLE.insert().values(
              job_id=job_id,
              job_type=job_type,
              status='pending',
              requested_timestamp=datetime.datetime.now(),
              sent_data=data,
              result_url=result_url,
              api_key=api_key,
              job_key=job_key))
  
          # Insert any (key, value) metadata pairs that the job has into the
          # metadata table.
          inserts = []
          for key, value in metadata.items():
              type_ = 'string'
              if not isinstance(value, basestring):
                  value = json.dumps(value)
                  type_ = 'json'
  
              # Turn strings into unicode to stop SQLAlchemy
              # "Unicode type received non-unicode bind param value" warnings.
              key = unicode(key)
              value = unicode(value)
  
              inserts.append(
                  {"job_id": job_id,
                   "key": key,
                   "value": value,
                   "type": type_}
              )
          if inserts:
              conn.execute(METADATA_TABLE.insert(), inserts)
          trans.commit()
      except Exception:
          trans.rollback()
          raise
      finally:
          conn.close()