Platform methods

showJobStateUsingJobState(JobState state)

Retrieves state information for the supplied JobState.

Input

state : job.internalId

Response

JobState (D)

Availability

Engage 7.3.3

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

showJobStateUsingJob(Job job)

Retrieve state information for the supplied Job.

Input

job : internalId + type

Response

JobState (D)

Availability

Engage 7.3.3

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

listJobStates(Org org, dateTime fromTime, dateTime toTime)

Lists outstanding requests (includes abuploads and reports. Words about NULL values.

Input

org : internalId or (externalId, parent, type)

Response

JobState[] (D)

Availability

Future

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• If fromTime and toTime are null then all JobStates are returned.
• If toTime is null then now is assumed.
• If fromTime is null then earliest item is returned.
• The maximum number of items returned using this method is 1,000.

showJobResultAsString(Job job)

Retrieves information from a previously completed job.

Input

job : internalId + type

Response

JobResult (D)

Availability

Engage 7.3.3

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Argument supplied is null
• ATTRIBUTE_NULL – Attribute supplied is null
• INVALID_STATE – If job has not completed successfully
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

The maximum size of the returned string is 1,000,000.

showJobResultAsStream(Job job)

Retrieves information from a previously completed job.

Input

job : internalId + type

Response

MTOM streamed attachment

Availability

Engage 10.1

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• INVALID_STATE – If job failed to complete successfully
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• There is no limitation on the return size. In case of an error (or errors), the error code and error message (or concatenated error codes and error messages if there are multiple errors) will be returned as part of a SOAPException, the format is:

  Error code1: Error message1. Error code2: Error message2.

listCapabilities(Org org, Capability sample)

Retrieves capabilities for the specified Organization.

Input

• org : internalId or (externalId, parent, type)
• sample : optional Capability to narrow the returned set.

Response

Capability[] (D)

Availability

Future

Errors returned

RESULT_TOO_LARGE – Result returned would be too large

Notes

• If sample is null all Capability will be returned.
• If sample is non-null all attributes must match.
• The maximum number of items returned using this method is 1,000.

listPreferences(Org org)

Retrieves current User preferences.

Input

org : internalId or (externalId, parent, type)

Response

Attribute[] (D)

Availability

Engage 7.7.0

Errors returned

No non-standard.

createSystemEvents(SystemEvent[] events, Org org)

Adds new system events to supplied organization.

Input

• events: all required attributes
• org : internalId or (externalId, parent, type)

Response

SystemEvent[] (D)

Availability

Engage 8.8.0

Errors returned

• ARG_INVALID_CHAR – Invalid Data, argument '%s' contains invalid characters
• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• The maximum number of items that may be supplied using this method is 100.

Required fields:

• Severity, type, category

listSystemEvents(Org org, SystemEvent sample, dateTime fromTime, dateTime toTime)

Retrieves a list of system events.

Input

• sample: Any attributes used to constrain search.
• org : internalId or (externalId, parent, type)

Response

SystemEvent[](D)

Availability

Engage 8.8.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• The supplied Org must be either a valid Account, Enterprise, SuperEnterprise or System.
• If fromTime and toTime are null then all items are returned.
• If toTime is null then now is assumed.
• If fromTime is null then earliest item is returned.
• The maximum number of items returned using this method is 200.

showSystemInfo()

Retrieves current System information.

Input

NONE

Response

Attribute[] (D)

Availability

Engage 7.3.3

Errors returned

No non-standard.

Notes

Attribute Name	Accessibility	Description	Since
APIVersion	General	Version of the API	7.3.3
BuildInfo	General	Build Identifier for Platform	7.3.3
EpochDate	General	Current date in milliseconds since 1970	8.1.0
NodeIdentifier	Internal Only	Identifier of the node responding to request	7.6.0
SoundBiteVersion	General	Version of the Platform	7.3.3
StackIdentifier	Internal Only	Identifier of the node responding to request	7.6.0
SystemDate	General	Current date on Platform (GMT)	7.3.3

createMetaDataGroup(MetaDataGroup metaDataGroup, Org org)

Creates a new MetaData Group associated with the identified org.

Input

• metaDataGroup: externalId
• org : internalId or (externalId, parent, type)

Response

MetaDataGroup (D)

Availability

Engage 8.7.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Argument supplied is null
• ATTRIBUTE_INVALID_CHAR – ExternalId contains invalid characters
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of active list definitions exceeded

Notes

The maximum number of MetaData Groups simultaneously available is 100.

deleteMetaDataGroup (MetaDataGroup metaDataGroup)

Deletes an existing MetaData Group.

Input

metaDataGroup: internalId or externalId and owner

Response

NONE

Availability

Engage 8.7.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

A deletion is only a soft delete and a deleted MetaData Group can still be reviewed via listMetaDataGroups

showMetaDataGroup(MetaDataGroup metaDataGroup)

Retrieves information about the supplied MetaData Group.

Input

metaDataGroup: internalId

Response

MetaDataGroup (D)

Availability

Engage 8.7.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

listMetaDataGroups(Org org, MetaDataGroups sample)

Lists MetaData Groups associated with the identified org.

Input

• org : internalId or (externalId, parent, type)
• sample: optional MetaData Group object to narrow the returned set.

Response

MetaDataGroup[] (K)

Availability

Engage 8.7.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – One of externalId or internalId must be non-null on the org
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• The maximum number of items returned using this method is 1,000.
• Only the attributes on the core entity are matched if a sample is supplied.

changeMetaDataGroup(MetaDataGroup metaDataGroup)

Updates fields/attributes of the supplied MetaData Group.

Input

metaDataGroup : internalId + any fields to be changed

Response

MetaDataGroup (D): updated MetaData Group

Availability

Engage 8.7.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_INVALID_CHAR – ExternalId contains invalid characters
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_TRUNCATED – List Definition name is too long
• NOT_SUPPORTED – Attempt to change the org associated with the list definition
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• It is not possible to change the org associated with a MetaData Group. If this is attempted a NOT_SUPPORTED error will be returned.
• This method will automatically delete the old MetaData Group and create a MetaData Group with a version number one greater than the MetaData Group. This means that the internalId on the returned MetaData Group is not the same as the internalId on the supplied MetaData Group.

createMetaData(MetaData metaData, BaseEntity baseEntity)

Creates a new metadata associated with the identified entity.

Input

• metadata: externalId and owner required
• baseEntity: externalId or internalId

Response

MetaData (D)

Availability

Engage 8.6.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Argument supplied is null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of metaData objects exceeded

deleteMetaData(MetaData metaData)

Deletes an existing metaData.

Input

metaData: internalId or externalId and owner

Response

NONE

Availability

Engage 8.6.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

showMetaData(MetaData metaData)

Retrieves system supported information about the supplied MetaData.

Input

metaData: externalId with associated BaseEntity (Org) Supported externalIds are timeZones, countryCodes, locales, regions, securityQuestions , agentBreakReasonCodes

Response

MetaData (D)

Availability

Engage 8.7.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

When retrieving metadata associated with the Engage platform the externalId should be provided along with a BaseEntity (Org) with an OrgType of system.

listMetaData(BaseEntity baseEntity, MetaData[] sample)

Lists metadata associated with the identified entity.

Input

• baseEntity: externalId or internalId
• sample: optional metadata array to narrow the returned set.

Response

MetaData[] (D)

Availability

Engage 8.6.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – One of externalId or internalId must be non-null on the baseEntity
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• The maximum number of items returned using this method is 100.
• Items in the sample array are a logical or.

changeMetaData(MetaData metaData)

Updates fields/attributes of the supplied metadata object.

Input

MetaData : internalId (or externalId and owner) + any fields to be changed

Response

MetaData (D): updated metadata object.

Availability

Engage 8.6.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• NOT_SUPPORTED – Attempt to change the baseEntity associated with the metaData
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

It is not possible to change the baseEntity associated with a MetaData. If this is attempted a NOT_SUPPORTED error will be returned.

addToMetaData(MetaData metaData, MetaDataElement[] metaDataElements)

Adds the supplied elements to the identified metaData object.

Input

• metaData: internalId (or externalId and owner)
• metaDataElements: The set of elements to be added to the metaData object.

Response

NONE

Availability

Engage 8.10

Errors returned

• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

The maximum number of elements supported using this method is 100.

deleteFromMetaData(MetaData metaData, MetaDataElement[] metaDataElements)

Deletes the supplied metaDataElements from the identified metaData.

Input

• metaData: internalId or externalId and owner
• metaDataElements: The set of metaDataElements to be deleted from the list.

Response

NONE

Availability

Engage 8.10

Errors returned

• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size

Notes

The maximum number of metaDataElements supported using this method is 1,000.

changeMetaDataElement(MetaDataElement metaDataElement)

Updates fields/attributes of the supplied metaDataElement.

Input

metaDataElement : externalId and parent + any fields to be changed

Response

MetaData (D): updated metaDataElement object

Availability

Engage 8.10

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• NOT_SUPPORTED – Attempt to change the baseEntity associated with the metaDataElement
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

It is not possible to change the baseEntity associated with a MetaDataElement. If this is attempted a NOT_SUPPORTED error will be returned.

listRecordings(Org org, Recording sample, dateTime fromTime, dateTime toTime)

Retrieves Recordings associated with this org.

Input

• org : internalId or (externalId, parent, type)
• sample : optional list of Recording attributes to narrow the returned set.

Response

Recording[] (D)

Availability

Engage 8.10

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• If sample is null – all Recordings within Org and timeframe will be returned.
• If fromTime and toTime are null then all items are returned.
• If toTime is null then now is assumed.
• If fromTime is null then earliest item is returned.
• The supplied Org must be either a valid Account or Enterprise.
• The maximum number of items returned using this method is 1,000.
• The only attributes currently supported on the sample are:
  • contactAttempt
  • duration (if positive then recordings greater than or equal to this length, if negative then recordings less than the provided length)
  • format

createRuleContext (RuleContext[] rules, RuleCategory ruleCategory)

Adds new rulecontexts for given ruleCategory.

Input

• rules: all required attributes
• ruleCategory: internalId

Response

RuleContext[] (D)

Availability

Engage 10.6.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of active notifications exceeded

Notes

Validation Checks:

• It will have authorization checks.
• This API will return errors in following cases:-
  • If ruleContext's externalId, priority are not provided.
  • If ruleCategory is not provided.
  • If category's internalId is not provided, or non-existent internal id is provided.
  • If ruleTemplate's internalId is not provided or non-existent internal id is provided.
  • If rule context name (externalId) exists within given category.
  • If rule context priority is not unique within given category

changeRuleContext (RuleContext rule)

Updates fields/attributes for supplied rule.

Input

rule: internalId + any fields to be changed.

Response

RuleContext (D): updated object

Availability

Engage 10.6.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ATTRIBUTE_INVALID_DATA – Invalid Data '%s

Notes

Validation checks:

• It will have authorization checks.
• This API will return error in following scenarios:
  • If internalId is not provided or not exists.
  • If given priority is not unique within category.
  • If given rule context name (externalId) is not unique within category.
• Update of rule context involves soft deleting rule context and creating new rule context. New rule context will have same associations as this rule context.

deleteRuleContext (RuleContext[] rules

Deletes rule.

Input

rules: internalIds.

Response

NONE

Availability

Engage 10.6.0.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

Validation checks:

• It will have authorization checks.
• This API will return error if internalId is not provided.

listRuleContexts (RuleCategory ruleCategory)

Lists rules for given ruleCategory.

Input

ruleCatgeory: internalId.

Response

RuleContext[] (D):

Availability

Engage 10.6.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

Validation checks

• It will have authorization checks.
• This API will return error if ruleCategory's internaIId is not provided

showRuleContext (RuleContext rule)

Retrieves information about supplied rule.

Input

ruleContext: internalId

Response

RuleContext (D)

Availability

Engage 10.6.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

Validation checks:

• It will have authorization checks.
• This API will return error if internalId of RuleContext is not provided.

createRuleCategory (RuleCategory ruleCategory, Org org)

Adds new rulecategory for given org.

Input

• ruleCategory: all required attributes
• org: internalId

Response

RuleCategory [] (D)

Availability

Future

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of active notifications exceeded

Notes

Validation Checks:

• Only enterprise admin user will be allowed to create ruleCategory.
• This API will return error in following cases:-
  • If category's externalId, type , is not provided
  • If org is null, or nonexistent.
  • If category type exists within given org (there can be only one type for an org).

changeRuleCategory (RuleCategory ruleCategory)

Updates fields/attributes for supplied ruleCategory.

Input

rule: internalId + any fields to be changed.

Response

RuleCategory (D): updated object

Availability

Future

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ATTRIBUTE_INVALID_DATA – Invalid Data '%s

Notes

Validation checks:

• It will have authorization checks.
• This API will return error in following scenarios:-
  • If internalId is not provided or not exists.
  • If given rule category name (externalId) is not unique within account.
• This API will use RuleContextManager's update, which will do soft delete of rule category and create new rule category.

deleteRuleCategory (RuleCategory[] ruleCategories)

Deletes ruleCategories.

Input

ruleCategories: internalIds.

Response

NONE

Availability

Future

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

Validation Checks:

• Only enterprise admin user will be allowed to delete ruleTemplate.
• API will throw error if following mandatory fields are not provided:
  • internalId
• API will throw error if non-existent internalId is provided.

listRuleCategories (Org org)

Lists ruleCategory for given org.

Input

org: internalId.

Response

RuleCategory[] (D):

Availability

Engage 10.6.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

Validation checks:

• Only enterprise admin user will be allowed to list rule categories.
• API will return error if org is not provided.

listRuleCatgoriesUsingRuleCategory (Org org , RuleCategory sample)

Lists ruleCategory for given org filter by sample category type

Input

• org: internalId or (externalId , type , parent)
• sample: type

Response

RuleCategory[] (D):

Availability

Engage 11.0.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ATTRIBUTE_INVALID_DATA – Attribute contains invalid data: '%s'.

Notes

Validation checks:

• API will return error if org is not provided.

showRuleCategory(RuleCategory ruleCategory)

Retrieves information about supplied ruleCategory.

Input

ruleCategory: internalId

Response

RuleCategory (D)

Availability

Future

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

Validation checks:

• Only enterprise admin user will be allowed to show rule category.
• API will throw error if following mandatory fields are not provided:-
  • internalId

createRuleTemplate (RuleTemplate ruleTemplate)

Adds new ruleTemplate for given org.

Input

rulesTemplate: externalId & all required attributes

Response

RuleTemplate (D)

Availability

Engage 11.0.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of active notifications exceeded

Notes

Validation Checks

• Only an enterprise admin user can create ruleTemplate.
• API will throw error if following mandatory fields are not provided:-
  • externalId
  • org
  • definition
  • definitionType

changeRuleTemplate (RuleTemplate ruleTemplate)

Updates fields/attributes for supplied ruleTemplate.

Input

ruleTemplate: internalId + any fields to be changed.

Response

RuleTemplate (D): updated object

Availability

Future

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ATTRIBUTE_INVALID_DATA – Invalid Data '%s

Notes

• It will have authorization checks.
• This API will return error in following scenarios:-
  • If internalId is not provided or not exists.
  • If given rule template name (externalId) is not unique within account.
• This API will use RuleContextManager's update, which will do soft delete of rule template and create new rule template.

deleteRuleTemplate (RuleTemplate ruleTemplate)

Deletes rule.

Input

ruleTemplate: internalIds.

Response

NONE

Availability

Engage 11.0.0.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

Validation Checks:

• Only an enterprise admin user will be allowed to delete ruleTemplate.
• API will throw error if following mandatory fields are not provided:-
  • internalId
• API will throw error if non-existent internalId is provided.

showRuleTemplate (RuleTemplate ruleTemplate)

Retrieves information about supplied ruleTemplate.

Input

ruleTemplate: internalId

Response

RuleTemplate (D)

Availability

Engage 11.0.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

Validation checks:

• It will have authorization checks.
• Only an enterprise admin user will be allowed to show ruleTemplate
• This API will return error if internalId of RuleTemplate is not provided.

listRuleTemplates (Org org)

Lists ruleTemplate for given org.

Input

org: internalId.

Response

RuleTemplate[] (D):

Availability

Engage 10.6.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

Validation checks:

• Only an enterprise admin user will be allowed to list ruleTemplates.
• API will return error if org is not provided

createRuleSetGroup (RuleSetGroup ruleSetGroup)

Creates ruleSetGroup

Input

• ruleSetGroup: all required information to create ruleSetGroup
• ruleCategory internalId should be specified for each ruleContext.
• Use listRuleCategoriesUsingRuleCategory API to access RuleCategory of type ‘List’ for the account.
• Provide RuleCategory of type ‘List’ in the sample in listRuleCategoriesUsingRuleCategory API.
• ruleTemplate internalId should be specified for each ruleContext.
• RuleTemplates ids will have to be hardcoded.
• Ids for different types of rule context –
• InputHandlerRule - id is 3
• PartitionRule - id is 4
• FilterRule - id is 5
• UploadRule – id is 6
• SpecificationRule – id is 7
• ConditionsRule – id is 8

Response

RuleSetGroup (D):

Availability

Engage 11.11.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_EXISTS – Object '%s' already exist
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ATTRIBUTE_INVALID_DATA – Attribute contains invalid data: '%s'.

Notes

Validation checks:

• API will have authorization checks.
• RuleSetGroup’s externalId and RuleSetGroup Org’s internalId and OrgType need to be provided. Also, ruleSetGroup’s type need to be provided. Type can be ‘Sequence’ or ‘Filter’.
• RuleSetGroup of type ‘Sequence’ will contain:-
• Atleast one RuleSet.
• RuleSet type will be assumed from ruleSetGroup.
• RuleSet can have maximum 5 rules. One for each following type:-
• InputHandler , Partition , Specification , Filter , Upload
• RuleSet should have at least 2 rules. One for each type InputHandler, Specification, Upload.
• Rule type InputHandler should provide attribute sequence as 1.
• Rule type Upload should provide have attribute sequence more than 5.
• RuleSet should have rules in following order:-
• InputHandler, Specification, Filter, Partition, Upload
• Rules should provide attribute sequence in order specified above. Please refer to table contains list of supported rulecontext types and corresponding supported attributes and their values in section 2.2.3.2.1.
• RuleSetGroup of type ‘Filter’ should contain:-
• Atleast one RuleSet.
• Can have maximum preference “api.platformManagement.filterListRule.maxRuleSetsAllowed” defined rule sets.
• Each ruleSet can have maximum preference “api.platformManagement.filterListRule.maxRulesAllowed” defined rules.
• It will throw error if attribute specification name is not active/existing in current account or master account.
• It will throw error if attribute ruleSetGroupId is not active/existing in current account hierarchy meaning current account or master account or system master account.
• It will throw error if there is a mismatch between ruleTemplate and rule type.

ruleTemplate name is mapped to rule type. (refer sb_rule_template table)

• Response will populate following error contexts:-
• ErrorContextConstant.DUPLICATE_RULE_SET_GROUP_NAME:- When duplicate ruleSetGroup name is provided.
• ErrorContextConstant.FIELD_VALUE_INVALID:- When attribute ‘fieldValue’ contains invalid value.
• ErrorContextConstant.CRITERIA_VALUE_INVALID:- When attribute ‘criteriaValue’ contains invalid value.

changeRuleSetGroup (RuleSetGroup ruleSetGroup , RuleSet[] ruleSets)

changes ruleSetGroup

Input

• ruleSetGroup: internalId or (externalId and owner)
• ruleSets: if new ruleSets should be assocaited to this ruleSetGroup

Response

RuleSetGroup (D):

• This API will update ruleSetGroup name , associated ruleSets if provided. It will soft delete existing ruleSetGroup associations.
• Also, if there are active virtual lists using this rule set group, it will be updated to use new ruleSetGroup

Availability

Engage 11.11.0.0

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_EXISTS – Object '%s' already exist
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ATTRIBUTE_INVALID_DATA – Attribute contains invalid data: '%s'.

Notes

Validation checks:

• API will have authorization checks.
• RuleSetGroup’s internalId or externalId and Org’s internalId and orgType need to be provided.
• At least one rule set need to be provided. It’s internalId or externalId need to be provided. It should exist.

deleteRuleSetGroup (RuleSetGroup[] ruleSetGroups)

deletes ruleSetGroup

Input

• ruleSetGroups: internalIds or (externalId and owner)

Response

None

• This API will soft delete ruleSetGroup and its assocaitions.
• Virtual lists using this rule set group will be soft deleted.
• Empty response will be returned

Availability

Engage 11.11.0.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ATTRIBUTE_INVALID_DATA – Attribute contains invalid data: '%s'.

Notes

Validation checks:

• API will have authorization checks.
• RuleSetGroup’s internalId or externalId and Org’s internalId and orgType need to be provided.
• If there are active virtual lists using this rule set, you can’t delete the rule set.

showRuleSetGroup (RuleSetGroup ruleSetGroup)

returns deeply populated information about input ruleSetGroup

Input

• ruleSetGroup: internalId or (externalId and owner)

Response

RuleSetGroup (D)

Availability

Engage 11.11.0.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ATTRIBUTE_INVALID_DATA – Attribute contains invalid data: '%s'.

Notes

Validation checks:

• API will have authorization checks.
• RuleSetGroup’s internalId or externalId and Org’s internalId and orgType need to be provided

listRuleSetGroups (Org org, RuleSetGroup sample)

Lists rule set groups of account

Input

• ruleSetGroups: internalIds or (externalId and owner)

Response

None

• This API will soft delete ruleSetGroup and its assocaitions.
• Virtual lists using this rule set group will be soft deleted.
• Empty response will be returned

Availability

Engage 11.11.0.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ATTRIBUTE_INVALID_DATA – Attribute contains invalid data: '%s'.

Notes

Validation checks:

• API will have authorization checks.
• Org’s internalId and OrgType need to be provided.
• If sample provided, any supported attribute or field need to be provided. Currently only RuleSetGroup externalId, type are supported.
• Null sample will result in all active ruleSetGroups in given account

createNotification (Notification notification)

Adds new notification for given or all stacks depending upon stackId provided.

Input

notification: all required attributes

Response

Notification (D)

Availability

Engage 11.5

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_EXISTS – Object '%s' already exists
• SYSTEM_LIMIT_EXCEEDED – maximum number of active notifications exceeded

Notes

• API can be accessed by SYSOPS, SB Admin users.
• Required fields:
  • type
  • Notification attributes

changeNotification (Notification notification)

Updates fields/attributes for supplied notification.

Input

internalId + any fields to be changed-

Response

Notification (D): updated object

Availability

Engage 11.5

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

API can be accessed by SYSOPS, SB Admin users.

deleteNotification (Notification notification)

Deletes notification.

Input

notification: internalId.

Response

NONE

Availability

Engage 11.5

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

API can be accessed by SYSOPS, SB Admin users.

showNotification (Notification notification)

Retrieves information about supplied notification.

Input

notification: internalId

Response

Notification (D)

Availability

Engage 11.5

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

• API can be accessed by SYSOPS, SB Admin users.
• API will return only active notification meeting input criteria.

listNotifications (User user , Notification sample)

Lists notification for given user. If user is passed as null, it returns system-wide notifications.

Input

• user: externalId.
• sample: optional list of notification attributes to narrow the returned set.

Response

Notification[] (D):

Availability

Engage 11.5

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• API can be accessed by SYSOPS, SB Admin users, when user is null.
• If sample is null – all users within Org will be returned.
• If sample is non-null all attributes must match

showNotificationView (NotificationView notificationView)

Retrieves notificationView for given notification, by this user.

Input

notificationView: internalId

Response

NotificationView (D)

Availability

Engage 11.5

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

createNotificationView (NotificationView notificationView)

Adds new notificationView.

Input

notificationView: all required attributes

Response

NotificationView (D)

Availability

Engage 11.5

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null

Notes

API can be accessed by SYSOPS, SB Admin users.

changeNotificationView (NotificationView notificationView)

Updates fields/attributes for supplied notificationView.

Input

notificationView: internalId + any fields to be changed.

Response

NotificationView (D): updated object

Availability

Engage 11.5

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

Supported fields:

• attribute numberOfViews
• attribute completedDate

createInboundDevice (Device device, Org org)

Creates a new device associated with the identified entity.

Input

• Device: device (externalId, attributes - name, description, inboundDeviceType, keywords)
• org: (internalId, org's type)

Response

Device(D)

Availability

Engage 11.6

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Argument supplied is null
• ATTRIBUTE_INVALID_CHAR – Attribute "%s" contains invalid characters
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_INVALID_DATA – Invalid Data '%s
• ATTRIBUTE_TOO_SMALL - Attribute is less than allowed minimum size.
• ATTRIBUTE_TOO_LARGE - Attribute '%s' exceeds allowed size
• ATTRIBUTE_INVALID_CHAR - Attribute "%s" contains invalid characters.
• OBJECT_EXISTS – Object '%s' already exists
• INBOUND_DEVICE_ALREADY_MAPPED_TO_KEYWORD - Keyword "%s" is already mapped to the short code "%s".
• INBOUND_LOCAL_TOUCH_CAPABILITY_NOT_FOUND - Capability for LocalTouch Inbound Device not found.
• INBOUND_DEVICE_ASSIGNED_ACTIVE_CAMPAIGN - Unable to reassign Inbound Device. The Caller ID associated with the Inbound Device is currently assigned to an active template in account "%s". Please go to Accounts Caller ID listing page and change the templates that are referencing the number.
• INBOUND_DEVICE_AGENT_DIAL_IN_REQUIRES_ACCT - Inbound Device cannot be set as Agent Login Script since no account is associated.
• INTERNAL_ERROR – Internal error
• Warning: INBOUND_DEVICE_AGENT_DIAL_IN_PRIMARY_SECONDARY_EXISTS - Inbound Device "%s" cannot be assigned as an Agent Login Script for this account. This account has already primary and secondary number assigned to it.

Notes

• Only SYSOPS_ROLE, ADMIN_ROLE, WSDL_ROLE users and user being a SBPartner are allowed to create InboundDevice without Org.
• Non SB admin users with ADMIN_ROLE, WSDL_ROLE are allowed to create inbound device, but have to provide account information.
• Attributes active, ownerInternalId, subCampaignInternalId are populated post device creation and returned.
• If inboundDeviceType is ShortCode and a device with externalid, ownerInternalId combination is already present, api adds keywords to the existing device.
• Supported fields:
  • attribute name
  • attribute description
  • attribute inboundDeviceType
  • attribute keywords
  • attribute active
  • attribute ownerInternalId
  • attribute subCampaignInternalId

changeInboundDevice(Device sample)

Changes fields of given InboundDevice.

Input

sample: device (internalId)

Response

Device[] (D):

Availability

Engage 11.6

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_INVALID_DATA – Invalid Data '%s
• ATTRIBUTE_TOO_SMALL - Attribute is less than allowed minimum size.
• ATTRIBUTE_TOO_LARGE - Attribute '%s' exceeds allowed size
• ATTRIBUTE_INVALID_CHAR - Attribute "%s" contains invalid characters.
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• INBOUND_DEVICE_ASSIGNED_ACTIVE_CAMPAIGN - Unable to reassign Inbound Device. The Caller ID associated with the Inbound Device is currently assigned to an active template in account "%s". Please go to Accounts Caller ID listing page and change the templates that are referencing the number.
• INBOUND_DEVICE_AGENT_DIAL_IN_REQUIRES_ACCT - Inbound Device cannot be set as Agent Login Script since no account is associated.
• INTERNAL_ERROR – Internal error
• INBOUND_TEXT_KEYWORD_ACTIVE - Cannot change ShortCode: {0}, since one of its keyword(s) is active. Along with new keywords provide all active keywords.
• INBOUND_LOCAL_TOUCH_CAPABILITY_NOT_FOUND - Capability for LocalTouch Inbound Device not found.
• INBOUND_DEVICE_ALREADY_MAPPED_TO_KEYWORD - Keyword "%s" is already mapped to the short code "%s".
• NOT_IMPLEMENTED - This Operation is not implemented.

Notes

• Only SYSOPS_ROLE, ADMIN_ROLE, WSDL_ROLE users and user being a SBPartner are allowed to change InboundDevice without Org.
• Non SB admin users with ADMIN_ROLE, WSDL_ROLE are allowed to change inbound device, but have to provide account information.
• Possible fields that can be modified are keywords, ownerInternalId. No other fields can be modified.If a user tries to update any other fields, API will not update those fields and will return empty data.
• Changing a device of type LocalTouch is not supported.
• Supported fields:-
  • attribute name
  • attribute description
  • attribute inboundDeviceType
  • attribute keywords
  • attribute active
  • attribute ownerInternalId
  • attribute subCampaignInternalId

showInboundDevice(Device sample)

Shows InboundDevice

Input

sample: device (internalId or (externalId and inboundDeviceType) or(externalId, inboundDeviceType = 'ShortCode' and keywords) or (internalId , inboundDeviceType = 'ShortCode' and keywords)

Response

Device[] (D):

Availability

Engage 11.6

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_INVALID_DATA – Invalid Data '%s
• INTERNAL_ERROR – Internal error
• AUTHORIZATION_FAILURE - Authorization failure {0}.
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

• Only SYSOPS_ROLE, ADMIN_ROLE, WSDL_ROLE users and user being a SBPartner are allowed to fetch InboundDevice without Org.
• Non SB admin users with ADMIN_ROLE, WSDL_ROLE are allowed to fetch inbound device, but have to provide account information.
• For showing ShortCode:-
  • user has to pass externaldId, inboundDeviceType and attribute keywords with a single keyword value or.
  • user has to pass internalId, if filter attributes inboundDeviceType, attribute keywords with a single keyword value is provided apply those.
• Supported fields:-
  • attribute name
  • attribute description
  • attribute inboundDeviceType
  • attribute keywords
  • attribute active
  • attribute ownerInternalId
  • attribute subCampaignInternalId

listInboundDevices(Org org, Device sample)

Lists inbound devices within given org.

Input

• org: internalId and org's type
• sample: device (inboundDeviceType)

Response

Device[] (D):

Availability

Engage 11.6

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_INVALID_DATA – Invalid Data '%s
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

• Only SYSOPS_ROLE, ADMIN_ROLE, WSDL_ROLE users and user being a SBPartner are allowed to fetch InboundDevices without Org.
• Non SB admin users with ADMIN_ROLE, WSDL_ROLE are allowed to fetch inbound devices, but have to provide account information.
• If org is null, fetch all non deleted devices
• If org is ENTERPRISE, fetch devices filtering by org.partner and deviceType.This will return devices that has accounts associated with the given partner.
• If org is ACCOUNT, fetch devices filtering by org.account and deviceType
• Supported fields:
  • attribute name
  • attribute description
  • attribute inboundDeviceType
  • attribute keywords
  • attribute active
  • attribute ownerInternalId
  • attribute subCampaignInternalId

deleteInboundDevice(Device sample)

Deletes InboundDevice.

Input

sample: device (internalId or (externalId, inboundDeviceType, if inboundDeviceType = 'ShortCode', then keywords) or (internalId , inboundDeviceType = 'ShortCode' and keywords))

Response

Device[] (D): empty

Availability

Engage 11.8

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_INVALID_DATA – Invalid Data '%s
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• INBOUND_DEVICE_ASSIGNED_ACTIVE_CAMPAIGN=Unable to reassign Inbound Device. The Caller ID associated with the Inbound Device is currently assigned to an active template in account {0}. Please go to Accounts Caller ID listing page and change the templates that are referencing the number.
• INBOUND_TEXT_KEYWORD_CANNOT_BE_DELETED=Cannot delete ShortCode: {0}, since one of its keywords is active.
• INTERNAL_ERROR – Internal error
• AUTHORIZATION_FAILURE - Authorization failure {0}.

Notes

• Only SYSOPS_ROLE, ADMIN_ROLE, WSDL_ROLE users and user being a SBPartner are allowed to fetch InboundDevice without Org.
• Non SB admin users with ADMIN_ROLE, WSDL_ROLE are allowed to fetch inbound device, but have to provide account information.
• For showing ShortCode:-
  • user has to pass externaldId, inboundDeviceType and attribute keywords with valueor.
  • user has to pass internalId, if filter attributes inboundDeviceType, attribute keywords with values is provided apply those.
• Supported fields:
  • attribute name
  • attribute description
  • attribute inboundDeviceType
  • attribute keywords
  • attribute active
  • attribute ownerInternalId
  • attribute subCampaignInternalId

createSecurityToken (User user, Integer type)

Creates a valid token including generating signature mac that includes signing the optional attributes.

Input

user : internalId/externalId or email address.

Response

NONE

Availability

Engage 11.8

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

Validation Checks:

• It will have authorization checks.
• Checks if it's email validation, password reset request.
• Returns empty response or else error in case of errors.
• Set UV _ IS_ACTIVE =false in SB_USER_VALIDATION for all existing records for this user id.
• Insert record for this user id and generated GUID.
• Successful validation would return empty response

validateSecurityToken (String url, User user)

Checks security token (signature and is valid Boolean).

Input

url : url that user has clicked.

Response

Returns a User object containing the user security questions and enterprise password reset parameters

Availability

Engage 11.8

Errors returned

• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

Notes

Validation Checks:

• It will have authorization checks.
• API validates either input URL or user.
• If URL is not null
  • Throws error when:
    • URL is tampered.
    • GUID extracted from URL is:
      • Non existing
      • Existing but associated to different user.
    • For Password reset requests:-
      • If IA_VALIDATION_ATTEMPT in SB_INTERNAL_USER is greater than 3 (managed by account preference password_reset.max.retries )
      • If URL is timed out. This can be checked against account preference password_reset.expiration.minutes , SB_USER_VALIDATION column UV _ TLM_DT
      • Increments SB_INTERNAL_USER column IA_VALIDATION_ATTEMPT by 1 in case of errors.
  • Successful validation :-
    • For Email validation requests:-
      • Updates IA_VALIDATION_STATE=2, IA _EMAIL_VALIDATED_DT= current date, IA_VALIDATION_ATTEMPT = 0 in SB_INTERNAL_USER table
      • Returns empty response.
• If user is not null
  • Validate user's entered security answers.
  • If successful
    • Reset IA_VALIDATION_ATTEMPT to 0 SB_INTERNAL_USER table.
    • Return empty response.
  • Else
    • Increment IA_VALIDATION_ATTEMPT in SB_INTERNAL_USER by 1

invalidateSecurityToken (SecurityToken securityToken)

Flips the valid token to false.

Input

securityToken: internalId (GUID).

Response

NONE

Availability

Engage 11.8

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Object being referenced does not exist

showGeoLocation(Org org, GeoLocation geolocation)

Show geographic coordinates for given location description.

Input

• org: internalId and org's type
• geolocation: GeoLocation

Response

GeoLocation: updated object with location coordinates.

Availability

Engage 12.2

Errors returned

• ATTRIBUTE_NULL - Cannot receive coordinates for given request data
• INTERNAL_ERROR - Cannot send geolocalization request for incorrect address
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• NOT_SUPPORTED - Feature disabled on account or system level

Notes

• All roles of Account type Org are permitted to send geolocation requests
• Only accouns with attribute account.geocoderServiceAllowed set to true are allowed to send geolocation requests

importRuleContextsUsingStream(Org org , DataHandler datahandler)

imports ruleContexts from input xml file to given org.

Input

• org: internalId and org's type
• datahandler: rules in XML format

Response

Empty response or any errors encountered

Availability

Engage 13.1

Errors returned

• ATTRIBUTE_INVALID_DATA - XML parse error, or schema validation error
• INTERNAL_ERROR - Error importing XML
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ARG_INVALID_DATA - If ruleType http header is invalid. Supported value 'Contact' , 'ContactAttempt'

listRuleContextsUsingStream(Org org , RuleCategory ruleCategory)

exports ruleContexts in xml format.

Input

• org: internalId and org's type
• ruleCategory: ruleCategory type. Supported values are 'Contact', 'ContactAttempt'

Response

DataHandler: response contains xml or errors encountered.

Availability

Engage 13.1

Errors returned

• ATTRIBUTE_INVALID_DATA - XML parse error, or schema validation error
• INTERNAL_ERROR - Error importing XML
• OBJECT_NOT_EXISTS – Object being referenced does not exist
• ARG_INVALID_DATA - If ruleType http header is invalid. Supported value 'Contact' , 'ContactAttempt'