/**
* @file Salesforce SOAP API
* @author Shinichi Tomita <shinichi.tomita@gmail.com>
*/
'use strict';
var _ = require('lodash/core');
var jsforce = require('../core');
var SOAP = require('../soap');
/**
* API class for Partner SOAP call
*
* @class
* @param {Connection} conn - Connection
*/
var SoapApi = module.exports = function(conn) {
this._conn = conn;
};
/**
* Call SOAP Api (Partner) endpoint
* @private
*/
SoapApi.prototype._invoke = function(method, message, schema, callback) {
var soapEndpoint = new SOAP(this._conn, {
xmlns: "urn:partner.soap.sforce.com",
endpointUrl: this._conn.instanceUrl + "/services/Soap/u/" + this._conn.version
});
return soapEndpoint.invoke(method, message, { result: schema }).then(function(res) {
return res.result;
}).thenCall(callback);
};
/* */
var Schemas = {};
/**
* @typedef SoapApi~LeadConvert
* @prop {String} convertedStatus - Status of converted lead
* @prop {String} leadId - Lead record Id to convert
* @prop {String} [accountId] - Account record Id to assign the converted record
* @prop {String} [contactId] - Contact record Id to assign the converted record
* @prop {Boolean} [doNotCreateOpportunity] - True if you don't want to create a new opportunity
* @prop {String} [opportunityName] - Name of opportunity to create
* @prop {Boolean} [overwriteLeadSource] - True if overwriting lead source
* @prop {String} [ownerId] - Owner Id
* @prop {Boolean} [sendNotificationEmail] - True if send notification email
*/
/**
* @typedef SoapApi~LeadConvertResult
* @prop {String} leadId - Lead record Id to convert
* @prop {String} [accountId] - Account record Id of converted lead
* @prop {String} [contactId] - Contact record Id of converted lead
* @prop {String} [opportunityId] - Opportunity record Id created in conversion
* @prop {Boolean} success - True if successfully converted
* @prop {Array.<Object>} errors - Error
*/
/**
* Converts a Lead into an Account, Contact, or (optionally) an Opportunity.
*
* @param {SoapApi~LeadConvert|Array.<SoapApi~LeadConvert>} leadConverts
* @param {Callback.<SoapApi~LeadConvertResult|Array.<SoapApi~LeadConvertResult>>} [callback] - Callback function
* @returns {Promise.<SoapApi~LeadConvertResult|Array.<SoapApi~LeadConvertResult>>}
*/
SoapApi.prototype.convertLead = function(leadConverts, callback) {
var schema = _.isArray(leadConverts) ? [ Schemas.LeadConvertResult ] : Schemas.LeadConvertResult;
return this._invoke("convertLead", { leadConverts: leadConverts }, schema, callback);
};
Schemas.LeadConvertResult = {
success: 'boolean',
errors: [],
leadId: 'string',
accountId: 'string',
contactId: 'string',
opportunityId: 'string'
};
/**
* @typedef SoapApi~MergeRequest
* @prop {Object} masterRecord - The merge destination record
* @prop {Array.<String>} recordToMergeIds - Ids of records to merge
*/
/**
* @typedef SoapApi~MergeResult
* @prop {Boolean} success - True if successfully merged
* @prop {Array.<Object>} errors - Error
* @prop {String} id - ID of the master record
* @prop {Array.<String>} mergedRecordIds - ID of the records that were merged into the master record
* @prop {Array.<String>} updatedRelatedIds - ID of all related records that were moved (re-parented) as a result of the merge
*/
/**
* Merge up to three records into one
*
* @param {SoapApi~MergeRequest|Array.<SoapApi~MergeRequest>} mergeRequests
* @param {Callback.<SoapApi~MergeResult|Array.<SoapApi~MergeResult>>} [callback] - Callback function
* @returns {Promise.<SoapApi~MergeResult|Array.<SoapApi~MergeResult>>}
*/
SoapApi.prototype.merge = function(mergeRequests, callback) {
var schema = _.isArray(mergeRequests) ? [ Schemas.MergeResult ] : Schemas.MergeResult;
return this._invoke("merge", { mergeRequests: mergeRequests }, schema, callback);
};
Schemas.MergeResult = {
success: 'boolean',
errors: [],
id: 'string',
mergedRecordIds: ['string'],
updatedRelatedIds: ['string']
};
/**
* @typedef SoapApi~EmptyRecycleBinResult
* @prop {String} id - ID of an sObject that you attempted to delete from the Recycle Bin
* @prop {Boolean} success - Whether the call succeeded (true) or not (false) for this record
* @prop {Array.<Object>} errors - Errors
*/
/**
* Delete records from the recycle bin immediately
*
* @param {Array.<String>} ids - Record ids to empty from recycle bin
* @param {Callback.<Array.<SoapApi~EmptyRecycleBinResult>>} [callback] - Callback function
* @returns {Promise.<Array.<SoapApi~EmptyRecycleBinResult>>}
*/
SoapApi.prototype.emptyRecycleBin = function(ids, callback) {
return this._invoke("emptyRecycleBin", { ids: ids }, [ Schemas.EmptyRecycleBinResult ], callback);
};
Schemas.EmptyRecycleBinResult = {
id: 'string',
success: 'boolean',
errors: []
};
/**
* @typedef SoapApi~DescribeTabSetResult
* @prop {String} label - The display label for this standard or custom app
* @prop {String} logoUrl - A fully qualified URL to the logo image associated with the standard or custom app
* @prop {String} namespace - Namespace of application package
* @prop {Boolean} selected - If true, then this standard or custom app is the user’s currently selected app
* @prop {Array.<SoapApi~DescribeTab>} tabs - An array of tabs that are displayed for the specified standard app or custom app
*/
/**
* @typedef SoapApi~DescribeTab
* @prop {Array.<Object>} colors - Array of color information used for a tab
* @prop {Boolean} custom - true if this is a custom tab
* @prop {String} iconUrl - The URL for the main 32 x 32 pixel icon for a tab
* @prop {Array.<Object>} icons - Array of icon information used for a tab
* @prop {String} label - The display label for this tab
* @prop {String} miniIconUrl - The URL for the 16 x 16 pixel icon that represents a tab
* @prop {String} name - The API name of the tab
* @prop {String} sobjectName - The name of the sObject that is primarily displayed on this tab
* @prop {String} url - A fully qualified URL for viewing this tab
*/
/**
* Returns information about the standard and custom apps available to the logged-in user
*
* @param {Callback.<Array.<SoapApi~DescribeTabSetResult>>} [callback] - Callback function
* @returns {Promise.<Array.<SoapApi~DescribeTabSetResult>>}
*/
SoapApi.prototype.describeTabs = function(callback) {
return this._invoke("describeTabs", {}, [ Schemas.DescribeTabSetResult ], callback);
};
Schemas.DescribeTabSetResult = {
label: 'string',
logoUrl: 'string',
namespace: 'string',
selected: 'boolean',
tabs: [{
colors: [{
theme: 'string',
color: 'string',
context: 'string'
}],
iconUrl: 'string',
icons: [{
theme: 'string',
height: 'number',
width: 'number',
url: 'string',
contentType: 'string'
}],
label: 'string',
custom: 'boolean',
miniIconUrl: 'string',
name: 'string',
sobjectName: 'string',
url: 'string'
}]
};
/**
* Retrieves the current system timestamp (Coordinated Universal Time (UTC) time zone) from the API
*
* @typedef SoapApi~ServerTimestampResult
* @prop {String} timestamp - Timestamp
*/
/**
* @param {Callback.<SoapApi~ServerTimestampResult>} [callback] - Callback function
* @returns {Promise.<SoapApi~ServerTimestampResult>}
*/
SoapApi.prototype.getServerTimestamp = function(callback) {
return this._invoke("getServerTimestamp", {}, Schemas.GetServerTimestampResult, callback);
};
Schemas.GetServerTimestampResult = {
timestamp: 'string'
};
/**
* @typedef SoapApi~UserInfoResult
* @prop {Boolean} accessibilityMode
* @prop {String} currencySymbol
* @prop {Number} orgAttachmentFileSizeLimit
* @prop {String} orgDefaultCurrencyIsoCode
* @prop {String} orgDisallowHtmlAttachments
* @prop {Boolean} orgHasPersonAccounts
* @prop {String} organizationId
* @prop {Boolean} organizationMultiCurrency
* @prop {String} organizationName
* @prop {String} profileId
* @prop {String} roleId
* @prop {Number} sessionSecondsValid
* @prop {String} userDefaultCurrencyIsoCode
* @prop {String} userEmail
* @prop {String} userFullName
* @prop {String} userId
* @prop {String} userLanguage
* @prop {String} userLocale
* @prop {String} userName
* @prop {String} userTimeZone
* @prop {String} userType
* @prop {String} userUiSkin
*/
/**
* Retrieves personal information for the user associated with the current session
*
* @param {Callback.<SoapApi~UserInfoResult>} [callback] - Callback function
* @returns {Promise.<SoapApi~UserInfoResult>}
*/
SoapApi.prototype.getUserInfo = function(callback) {
return this._invoke("getUserInfo", {}, Schemas.GetUserInfoResult, callback);
};
Schemas.GetUserInfoResult = {
accessibilityMode: 'boolean',
currencySymbol: 'string',
orgAttachmentFileSizeLimit: 'number',
orgDefaultCurrencyIsoCode: 'string',
orgDisallowHtmlAttachments: 'boolean',
orgHasPersonAccounts: 'boolean',
organizationId: 'string',
organizationMultiCurrency: 'boolean',
organizationName: 'string',
profileId: 'string',
roleId: 'string',
sessionSecondsValid: 'number',
userDefaultCurrencyIsoCode: 'string',
userEmail: 'string',
userFullName: 'string',
userId: 'string',
userLanguage: 'string',
userLocale: 'string',
userName: 'string',
userTimeZone: 'string',
userType: 'string',
userUiSkin: 'string'
};
/**
* Sets the specified user’s password to the specified value
*
* @param {String} userId - User Id to set password
* @param {String} password - New password
* @param {Callback.<String>} [callback] - Callback function
* @returns {Promise.<String>}
*/
SoapApi.prototype.setPassword = function(userId, password, callback) {
return this._invoke("setPassword", { userId: userId, password: password }, callback);
};
/**
* @typedef SoapApi~ResetPasswordResult
* @prop {String} password
*/
/**
* Resets the specified user’s password
*
* @param {String} userId - User Id to set password
* @param {String} password - New password
* @param {Callback.<SoapApi~ResetPasswordResult>} [callback] - Callback function
* @returns {Promise.<SoapApi~ResetPasswordResult>}
*/
SoapApi.prototype.resetPassword = function(userId, callback) {
return this._invoke("resetPassword", { userId: userId }, callback);
};
/*--------------------------------------------*/
/*
* Register hook in connection instantiation for dynamically adding this API module features
*/
jsforce.on('connection:new', function(conn) {
conn.soap = new SoapApi(conn);
});
module.exports = SoapApi;