Source: api/soap.js

  1. /**
  2.  * @file Salesforce SOAP API
  3.  * @author Shinichi Tomita <shinichi.tomita@gmail.com>
  4.  */
  6. 'use strict';
  8. var _ = require('lodash/core');
  9. var jsforce = require('../core');
  10. var SOAP = require('../soap');
  12. /**
  13.  * API class for Partner SOAP call
  14.  *
  15.  * @class
  16.  * @param {Connection} conn - Connection
  17.  */
  18. var SoapApi = module.exports = function(conn) {
  19.   this._conn = conn;
  20. };
  22. /**
  23.  * Call SOAP Api (Partner) endpoint
  24.  * @private
  25.  */
  26. SoapApi.prototype._invoke = function(method, message, schema, callback) {
  27.   var soapEndpoint = new SOAP(this._conn, {
  28.     xmlns: "urn:partner.soap.sforce.com",
  29.     endpointUrl: this._conn.instanceUrl + "/services/Soap/u/" + this._conn.version
  30.   });
  31.   return soapEndpoint.invoke(method, message, { result: schema }).then(function(res) {
  32.     return res.result;
  33.   }).thenCall(callback);
  34. };
  37. /* */
  38. var Schemas = {};
  40. /**
  41.  * @typedef SoapApi~LeadConvert
  42.  * @prop {String} convertedStatus - Status of converted lead
  43.  * @prop {String} leadId - Lead record Id to convert
  44.  * @prop {String} [accountId] - Account record Id to assign the converted record
  45.  * @prop {String} [contactId] - Contact record Id to assign the converted record
  46.  * @prop {Boolean} [doNotCreateOpportunity] - True if you don't want to create a new opportunity
  47.  * @prop {String} [opportunityName] - Name of opportunity to create
  48.  * @prop {Boolean} [overwriteLeadSource] - True if overwriting lead source
  49.  * @prop {String} [ownerId] - Owner Id
  50.  * @prop {Boolean} [sendNotificationEmail] - True if send notification email
  51.  */
  52. /**
  53.  * @typedef SoapApi~LeadConvertResult
  54.  * @prop {String} leadId - Lead record Id to convert
  55.  * @prop {String} [accountId] - Account record Id of converted lead
  56.  * @prop {String} [contactId] - Contact record Id of converted lead
  57.  * @prop {String} [opportunityId] - Opportunity record Id created in conversion
  58.  * @prop {Boolean} success - True if successfully converted
  59.  * @prop {Array.<Object>} errors - Error
  60.  */
  61. /**
  62.  * Converts a Lead into an Account, Contact, or (optionally) an Opportunity.
  63.  *
  64.  * @param {SoapApi~LeadConvert|Array.<SoapApi~LeadConvert>} leadConverts
  65.  * @param {Callback.<SoapApi~LeadConvertResult|Array.<SoapApi~LeadConvertResult>>} [callback] - Callback function
  66.  * @returns {Promise.<SoapApi~LeadConvertResult|Array.<SoapApi~LeadConvertResult>>}
  67.  */
  68. SoapApi.prototype.convertLead = function(leadConverts, callback) {
  69.   var schema = _.isArray(leadConverts) ? [ Schemas.LeadConvertResult ] : Schemas.LeadConvertResult;
  70.   return this._invoke("convertLead", { leadConverts: leadConverts }, schema, callback);
  71. };
  72. Schemas.LeadConvertResult = {
  73.   success: 'boolean',
  74.   errors: [],
  75.   leadId: 'string',
  76.   accountId: 'string',
  77.   contactId: 'string',
  78.   opportunityId: 'string'
  79. };
  81. /**
  82.  * @typedef SoapApi~MergeRequest
  83.  * @prop {Object} masterRecord - The merge destination record
  84.  * @prop {Array.<String>} recordToMergeIds - Ids of records to merge
  85.  */
  86. /**
  87.  * @typedef SoapApi~MergeResult
  88.  * @prop {Boolean} success - True if successfully merged
  89.  * @prop {Array.<Object>} errors - Error
  90.  * @prop {String} id - ID of the master record
  91.  * @prop {Array.<String>} mergedRecordIds - ID of the records that were merged into the master record
  92.  * @prop {Array.<String>} updatedRelatedIds - ID of all related records that were moved (re-parented) as a result of the merge
  93.  */
  95. /**
  96.  * Merge up to three records into one
  97.  *
  98.  * @param {SoapApi~MergeRequest|Array.<SoapApi~MergeRequest>} mergeRequests
  99.  * @param {Callback.<SoapApi~MergeResult|Array.<SoapApi~MergeResult>>} [callback] - Callback function
  100.  * @returns {Promise.<SoapApi~MergeResult|Array.<SoapApi~MergeResult>>}
  101.  */
  102. SoapApi.prototype.merge = function(mergeRequests, callback) {
  103.   var schema = _.isArray(mergeRequests) ? [ Schemas.MergeResult ] : Schemas.MergeResult;
  104.   return this._invoke("merge", { mergeRequests: mergeRequests }, schema, callback);
  105. };
  106. Schemas.MergeResult = {
  107.   success: 'boolean',
  108.   errors: [],
  109.   id: 'string',
  110.   mergedRecordIds: ['string'],
  111.   updatedRelatedIds: ['string']
  112. };
  115. /**
  116.  * @typedef SoapApi~EmptyRecycleBinResult
  117.  * @prop {String} id - ID of an sObject that you attempted to delete from the Recycle Bin
  118.  * @prop {Boolean} success - Whether the call succeeded (true) or not (false) for this record
  119.  * @prop {Array.<Object>} errors - Errors
  120.  */
  121. /**
  122.  * Delete records from the recycle bin immediately
  123.  *
  124.  * @param {Array.<String>} ids - Record ids to empty from recycle bin
  125.  * @param {Callback.<Array.<SoapApi~EmptyRecycleBinResult>>} [callback] - Callback function
  126.  * @returns {Promise.<Array.<SoapApi~EmptyRecycleBinResult>>}
  127.  */
  128. SoapApi.prototype.emptyRecycleBin = function(ids, callback) {
  129.   return this._invoke("emptyRecycleBin", { ids: ids }, [ Schemas.EmptyRecycleBinResult ], callback);
  130. };
  131. Schemas.EmptyRecycleBinResult = {
  132.   id: 'string',
  133.   success: 'boolean',
  134.   errors: []
  135. };
  138. /**
  139.  * @typedef SoapApi~DescribeTabSetResult
  140.  * @prop {String} label - The display label for this standard or custom app
  141.  * @prop {String} logoUrl - A fully qualified URL to the logo image associated with the standard or custom app
  142.  * @prop {String} namespace - Namespace of application package
  143.  * @prop {Boolean} selected - If true, then this standard or custom app is the user’s currently selected app
  144.  * @prop {Array.<SoapApi~DescribeTab>} tabs - An array of tabs that are displayed for the specified standard app or custom app
  145.  */
  146. /**
  147.  * @typedef SoapApi~DescribeTab
  148.  * @prop {Array.<Object>} colors - Array of color information used for a tab
  149.  * @prop {Boolean} custom - true if this is a custom tab
  150.  * @prop {String} iconUrl - The URL for the main 32 x 32 pixel icon for a tab
  151.  * @prop {Array.<Object>} icons - Array of icon information used for a tab
  152.  * @prop {String} label - The display label for this tab
  153.  * @prop {String} miniIconUrl - The URL for the 16 x 16 pixel icon that represents a tab
  154.  * @prop {String} name - The API name of the tab
  155.  * @prop {String} sobjectName - The name of the sObject that is primarily displayed on this tab
  156.  * @prop {String} url - A fully qualified URL for viewing this tab
  157.  */
  158. /**
  159.  * Returns information about the standard and custom apps available to the logged-in user
  160.  *
  161.  * @param {Callback.<Array.<SoapApi~DescribeTabSetResult>>} [callback] - Callback function
  162.  * @returns {Promise.<Array.<SoapApi~DescribeTabSetResult>>}
  163.  */
  164. SoapApi.prototype.describeTabs = function(callback) {
  165.   return this._invoke("describeTabs", {}, [ Schemas.DescribeTabSetResult ], callback);
  166. };
  167. Schemas.DescribeTabSetResult = {
  168.   label: 'string',
  169.   logoUrl: 'string',
  170.   namespace: 'string',
  171.   selected: 'boolean',
  172.   tabs: [{
  173.     colors: [{
  174.       theme: 'string',
  175.       color: 'string',
  176.       context: 'string'
  177.     }],
  178.     iconUrl: 'string',
  179.     icons: [{
  180.       theme: 'string',
  181.       height: 'number',
  182.       width: 'number',
  183.       url: 'string',
  184.       contentType: 'string'
  185.     }],
  186.     label: 'string',
  187.     custom: 'boolean',
  188.     miniIconUrl: 'string',
  189.     name: 'string',
  190.     sobjectName: 'string',
  191.     url: 'string'
  192.   }]
  193. };
  195. /**
  196.  * Retrieves the current system timestamp (Coordinated Universal Time (UTC) time zone) from the API
  197.  *
  198.  * @typedef SoapApi~ServerTimestampResult
  199.  * @prop {String} timestamp - Timestamp
  200.  */
  201. /**
  202.  * @param {Callback.<SoapApi~ServerTimestampResult>} [callback] - Callback function
  203.  * @returns {Promise.<SoapApi~ServerTimestampResult>}
  204.  */
  205. SoapApi.prototype.getServerTimestamp = function(callback) {
  206.   return this._invoke("getServerTimestamp", {}, Schemas.GetServerTimestampResult, callback);
  207. };
  208. Schemas.GetServerTimestampResult = {
  209.   timestamp: 'string'
  210. };
  212. /**
  213.  * @typedef SoapApi~UserInfoResult
  214.  * @prop {Boolean} accessibilityMode
  215.  * @prop {String} currencySymbol
  216.  * @prop {Number} orgAttachmentFileSizeLimit
  217.  * @prop {String} orgDefaultCurrencyIsoCode
  218.  * @prop {String} orgDisallowHtmlAttachments
  219.  * @prop {Boolean} orgHasPersonAccounts
  220.  * @prop {String} organizationId
  221.  * @prop {Boolean} organizationMultiCurrency
  222.  * @prop {String} organizationName
  223.  * @prop {String} profileId
  224.  * @prop {String} roleId
  225.  * @prop {Number} sessionSecondsValid
  226.  * @prop {String} userDefaultCurrencyIsoCode
  227.  * @prop {String} userEmail
  228.  * @prop {String} userFullName
  229.  * @prop {String} userId
  230.  * @prop {String} userLanguage
  231.  * @prop {String} userLocale
  232.  * @prop {String} userName
  233.  * @prop {String} userTimeZone
  234.  * @prop {String} userType
  235.  * @prop {String} userUiSkin
  236.  */
  237. /**
  238.  * Retrieves personal information for the user associated with the current session
  239.  *
  240.  * @param {Callback.<SoapApi~UserInfoResult>} [callback] - Callback function
  241.  * @returns {Promise.<SoapApi~UserInfoResult>}
  242.  */
  243. SoapApi.prototype.getUserInfo = function(callback) {
  244.   return this._invoke("getUserInfo", {}, Schemas.GetUserInfoResult, callback);
  245. };
  246. Schemas.GetUserInfoResult = {
  247.   accessibilityMode: 'boolean',
  248.   currencySymbol: 'string',
  249.   orgAttachmentFileSizeLimit: 'number',
  250.   orgDefaultCurrencyIsoCode: 'string',
  251.   orgDisallowHtmlAttachments: 'boolean',
  252.   orgHasPersonAccounts: 'boolean',
  253.   organizationId: 'string',
  254.   organizationMultiCurrency: 'boolean',
  255.   organizationName: 'string',
  256.   profileId: 'string',
  257.   roleId: 'string',
  258.   sessionSecondsValid: 'number',
  259.   userDefaultCurrencyIsoCode: 'string',
  260.   userEmail: 'string',
  261.   userFullName: 'string',
  262.   userId: 'string',
  263.   userLanguage: 'string',
  264.   userLocale: 'string',
  265.   userName: 'string',
  266.   userTimeZone: 'string',
  267.   userType: 'string',
  268.   userUiSkin: 'string'
  269. };
  271. /**
  272.  * Sets the specified user’s password to the specified value
  273.  *
  274.  * @param {String} userId - User Id to set password
  275.  * @param {String} password - New password
  276.  * @param {Callback.<String>} [callback] - Callback function
  277.  * @returns {Promise.<String>}
  278.  */
  279. SoapApi.prototype.setPassword = function(userId, password, callback) {
  280.   return this._invoke("setPassword", { userId: userId, password: password }, callback);
  281. };
  283. /**
  284.  * @typedef SoapApi~ResetPasswordResult
  285.  * @prop {String} password
  286.  */
  287. /**
  288.  * Resets the specified user’s password
  289.  *
  290.  * @param {String} userId - User Id to set password
  291.  * @param {String} password - New password
  292.  * @param {Callback.<SoapApi~ResetPasswordResult>} [callback] - Callback function
  293.  * @returns {Promise.<SoapApi~ResetPasswordResult>}
  294.  */
  295. SoapApi.prototype.resetPassword = function(userId, callback) {
  296.   return this._invoke("resetPassword", { userId: userId }, callback);
  297. };
  300. /*--------------------------------------------*/
  301. /*
  302.  * Register hook in connection instantiation for dynamically adding this API module features
  303.  */
  304. jsforce.on('connection:new', function(conn) {
  305.   conn.soap = new SoapApi(conn);
  306. });
  309. module.exports = SoapApi;