Embed Size (px)
Citation preview
Tripolis Dialogue
Web services API 2.0
TripolisDialogue-webservices,version3.16-API2.0ReferenceGuide–October2016 p.2
TableofContentsIntroduction ............................................................................................................................................................................ 3Examplecall ............................................................................................................................................................................ 4Servicesoverview ................................................................................................................................................................... 6
Generic.............................................................................................................................................................................6Contacts............................................................................................................................................................................6Content.............................................................................................................................................................................6Publishing.........................................................................................................................................................................6Campaign..........................................................................................................................................................................6Reporting/analysis..........................................................................................................................................................6
MTOMvsNO-MTOM .............................................................................................................................................................. 7Authorities .............................................................................................................................................................................. 8AuthInfo .................................................................................................................................................................................. 8Dialogue application instance ................................................................................................................................................. 9getServiceInfo ......................................................................................................................................................................... 9Responsecodes .................................................................................................................................................................... 10
TripolisDialogue-webservices,version3.16-API2.0ReferenceGuide–October2016 p.3
Introduction
WhatistheSOAPWebServiceAPI2.0
TheTripolisDialogueSOAPAPIfacilitatesremoteaccessformanagingDialogue,orforit’sintegration,withouthavingtoaccessDialogue’sapplicationinterface(GUI)SOAP(SimpleObjectAccessProtocol)isamessagingprotocolthatallowsprogramstocommunicateusingHTTPandXML.TripolisusestheSOAPandWSDLstandardswhichareplatformandlanguageindependent.Forusageofthewebservicealicenseisrequired,licensesareactivatedbytheTripolisSystemAdministrators.WhyUsetheSOAPWebServiceAPI2.0
TheTripolisDialogueSOAPAPI2.0isanextensivewebservicewhichfacilitatescommunicationbetweenanyapplicationandDialoguebymakinguseXMLfilescontainingaheaderwithauthenticationInfoandabodywiththeactualcall.TheAPI2.0webservicegivesyourdevelopersaccesstomanyofthedata,content,andcampaignfeaturesofDialogue.BymakinguseofourAPI2.0youcanbuildyourownbi-directionaldatatransfers,campaignmanagementapplications,andotherapplicationsthatneedtointerfacewithyourDialogueclientfromaremotelocation.
PrerequisitesforUsingtheSOAPWebServiceAPI
• Tomakeuseofthewebservice,youneedaStandardAPIuserforDialoguewithAdvancedAPIuserrights(theserightsneedtobesetbyTripolissupport).
• Allowyourdevelopmentenvironmenttoaccessserviceslistedat:https://<instance>.tripolis.com/api2/docs/apieghttps://td35.tripolis.com/api2/docs/api
• Makesuretoconnecttotherightendpoint,wehavecategorizedourservicesthismeanseachcategoryhasit’sownend-point.EgourSubscriptionService:https://<instance>.tripolis.com/api2/soap/SubscriptionService?wsdl
TripolisDialogue-webservices,version3.16-API2.0ReferenceGuide–October2016 p.4
Examplecall
subscribeContact(partofourSubscriptionService):subscribes(un)confirmed,unsubscribesorupdatescontactswithoptionalemailpublication.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" <soap:Header> <ser:authInfo> <client>Tripolis Demo</client> <username>[email protected]</username> <password></password> </ser:authInfo> <ser:responseLanguage>?</ser:responseLanguage> </soap:Header> <soap:Body> <sub:subscribeContact> <!—Most xml items can be identitfied by either name or unique encrypted id--> <subscribeContactRequest> <contactDatabase> <id>[contactDatabaseId]/id> <name>[contactDatabaseName]/</name> </contactDatabase> <!— workspace transactional message --> <workspace> <id>[workspaceId]/</id> <name>[workspaceName]</name> </workspace> <!—Id or unique contact field in order to create or update contact--> <contactId>[contactId]</contactId> <contactFields> <contactField> <!—use id or name of contactField --> <id>[contactFieldId]</id> <name>[contactFieldName]</name> <value>[value of contactField]</value> </contactField> </contactFields> <contactGroupSubscriptions> <!--1 or more repetitions:--> <contactGroupSubscription> <contactGroup> <id>[contactGroupId]</id> <name>[contactGroupName]</name> </contactGroup> <!—1=confirmed / 0=unconfirmed--> <confirmed>?</confirmed> </contactGroupSubscription> </contactGroupSubscriptions> <contactGroupUnSubscriptions> <!--1 or more repetitions:--> <contactGroup> <id>[contactGroupId]</id> <name>[contactGroupName]</name> </contactGroup> </contactGroupUnSubscriptions> <directEmail> <id>[directEmailId]</id> <name>[directEmailName]</name> </directEmail> <newsletter> <id>[newsletterId]</id> <name>[newsletterName]</name> </newsletter> <!— temporary variables for content of transactional message--> <jobProperties> <property>
TripolisDialogue-webservices,version3.16-API2.0ReferenceGuide–October2016 p.5
<key>[key]</key> <value>[value]</value> </property> </jobProperties> <ip>?</ip> <!—required--> <reference>?</reference> </subscribeContactRequest> </sub:subscribeContact> </soap:Body> </soap:Envelope>
Responseexample:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> <ns2:responseLanguage xmlns:ns2="http://services.tripolis.com/">en</ns2:responseLanguage> </soap:Header> <soap:Body> <ns3:subscribeContactResponse xmlns:ns2="http://contact.services.tripolis.com/" xmlns:ns3="http://subscription.services.tripolis.com/" xmlns:ns4="http://services.tripolis.com/"> <response> <id>yKreYZGJx3_wK2T2K1CMqw</id> </response> </ns3:subscribeContactResponse> </soap:Body> </soap:Envelope>
Responseprovidescreatedorupdated(encrypted)contactid.
ServicesoverviewWehavecategorizedourcallsoverthefollowingtopics:
Generic
• ClientDomainService;formaintainingClientDomains• FtpAccountService;foradministeringS/FTPaccounts• UserService;APIandusersinformation
Contacts
• ContactDatabaseService,formaintainingContactDatabases• ContactDatabaseFieldGroupService,formaintainingFieldGroups• ContactDatabaseFieldService,formaintainFields• ContactGroupService,formaintainingContactGroups• SmartGroupService,formaintainingSmartGroups• ContactService,formaintainingContacts• ImportService,forimportingContacts• SubscriptionService,forsubscribing/updatingContacts
Content
• WorkspaceService,formaintainingWorkspaces• ArticleTypeService,formaintainingArticleTypes• ArticleFieldService,formaintainingArticleFields• ArticleService,formaintainingArticles• AttachmentService(mtom),formaintainingAttachments• ImageService(mtom),formaintainingImages• DirectEmailTypeService,formaintainingDirectEmailTypes• DirectEmailService,formaintainingDirectEmails(editions)• NewsletterTypeService,formaintainingNewsletterTypes• NewsletterTemplateService,formaintainingNewsletterTemplates• NewsletterSectionService,formaintainingNewsletterSections• NewsletterService,formaintainingNewletters(editions)• NewsletterArticleTemplateService,formaintainArticleTemplates• SmsTypeService,formaintainingSMSTypes• SmsMessageService,formaintainingSMSMessages
Publishing
• PublishingService,forpublishingMailandSMSjobs• MailJobService,formaintainingMailJobs• SmsJobService,formaintainingSMSJobs
Campaign
• CampaignDefinitionService,forretrievingCampaignDefinitions• CampaignService,formaintainingCampaignsRuns
Reporting/analysis
• ReportingService,forretrievingresponsedata
TripolisDialogue-webservices,version3.16-API2.0ReferenceGuide–October2016 p.7
MTOMvsNO-MTOM
SincePHPand.NETimplementationsareknowntoexperiencedifficultieswithhandlingMTOMattachmentsweofferourwebservicedefaultasNO-MTOM,withtheexceptionofAttachmentService,ImageServiceandExportService.ThesecallsareavailableinbothMTOMandNO-MTOM.MTOMistherecommendedW3CMessageTransmissionOptimizationMechanism,amethodofefficientlysendingbinarydatatoandfromWebservices.TheefficiencyclaimofMTOMreferstothesizeofthemessagessentacrossthewire.SinceSOAPusesXML,anybinarydataintheSOAPmessagewillhavetobeencodedastext.ThisisusuallydoneusingBase64encodingwhichincreasesthesizeofthebinarydataby33%.MTOMprovidesawaytosendthebinarydatainitsoriginalbinaryform,avoidinganyincreaseinsizeduetoencodingitintext.
TripolisDialogue-webservices,version3.16-API2.0ReferenceGuide–October2016 p.8
Authorities
MODULE_CAMPAIGN=CampaignMODULE_CONTACT=ContactMODULE_CONTENT=ContentMODULE_OUTBOUND=OutboundMODULE_REPORT=ReportMODULE_SETUP=SetupMODULE_SUPPORT=SupportROLE_ADMIN=ClientdomainAdministratorROLE_ADVANCED=ClientdomainAdvancedUserROLE_API_ADVANCED=AdvancedAPIuserROLE_API_BOUNCEHANDLER=BouncehandleruserROLE_API_STANDARD=StandardAPIuserROLE_INTERACTIVE=InteractiveuserROLE_PARTNER_ADMIN=PartnerdomainAdministratorROLE_SYSTEM_ADMIN=SystemAdministratorROLE_SYSTEM_ATTACHMENT=ContentAttachmentManagementROLE_SYSTEM_USER=SystemUserROLE_USER=ClientdomainUserSUBMODULE_CONTENT_DIRECT_MAIL=ContentDirectMailSUBMODULE_CONTENT_NEWSLETTER=ContentNewsletterSUBMODULE_CONTENT_SMS=ContentSMSSUBMODULE_OUTBOUND_MAIL=OutboundMailSUBMODULE_OUTBOUND_SMS=OutboundSMSSUBMODULE_REPORT_CONTACTS=ReportContactsSUBMODULE_REPORT_PUBLISHING=ReportPublishingSUBMODULE_SETUP_APPLICATION=SetupApplicationSUBMODULE_SETUP_CONTACT=SetupContactSUBMODULE_SETUP_CONTENT=SetupContentSUBMODULE_SETUP_PUBLISHING=SetupPublishing
AuthInfo
IneveryrequesttheauthInfoinformationisrequiredforauthenticationandpermissionpurposes.ForsecurityreasonsweadvisetoconfigureaseparateAPIuser,notrelatedtoaperson,withrestrictedaccesstoyourclientdomaindata,andwithoutaccesstoGUI.
<ser:authInfo> <client>CLIENT NAME</client> <username>USER NAME</username> <password>PASSWORD</password> </ser:authInfo>
Forexample:
<ser:authInfo> <client>Tripolis API</client> <username>[email protected]</username> <password>Xxxxx</password> </ser:authInfo>
TripolisDialogue-webservices,version3.16-API2.0ReferenceGuide–October2016 p.9
DialogueapplicationinstanceInthisdocumentyouwillfindtheplaceholder<instance>.DependingontheDialogueapplicationinstanceyouarerunningon,youmustfillintherightsubdomain.Forinstance,ifyouarerunningontheTD42instance,youreplace<instance>with“td42”whichwouldresultinaurlsimi-larto:https://td42.tripolis.com/api2/soap/ClientDomainService?wsdl
getServiceInfoAllserviceshaveamethodgetServiceInfo.Withthismethodyoucancheckiftheserviceisavailable.Requestexample:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://services.tripolis.com/"> <soap:Header/> <soap:Body> <ser:getServiceInfo/> </soap:Body> </soap:Envelope>
Responseexample:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> <ns2:responseLanguage xmlns:ns2="http://services.tripolis.com/">en</ns2:responseLanguage> </soap:Header> <soap:Body> <ns2:getServiceInfoResponse xmlns:ns2="http://services.tripolis.com/"> <response> <message>The ClientDomainService is alive</message> <serviceInfoItems> <serviceInfoItem> <key>buildNumber</key> <value>2011-11-30-15:07:58</value> </serviceInfoItem> <serviceInfoItem> <key>apiVersion</key> <value>2.0</value> </serviceInfoItem> <serviceInfoItem> <key>dialogueVersion</key> <value>3.5.2</value> </serviceInfoItem> </serviceInfoItems> </response> </ns2:getServiceInfoResponse> </soap:Body> </soap:Envelope>
TripolisDialogue-webservices,version3.16-API2.0ReferenceGuide–October2016 p.10
Responsecodes
code name type category
100 CALL_NOT_ALLOWED FAULT 200 SUCCESS SUCCESS 300 AUTHENTICATION FAULT AUTHENTICATION400 VALIDATION FAULT VALIDATION401 ALREADY_EXISTS FAULT VALIDATION402 REQUIRED FAULT VALIDATION403 INVALID FAULT VALIDATION404 VALUE_TOO_LOW FAULT VALIDATION405 VALUE_TOO_HIGH FAULT VALIDATION406 ONLY_ONE_ALLOWED FAULT VALIDATION407 NOT_FOUND FAULT VALIDATION408 NOT_ALLOWED FAULT VALIDATION409 VALUE_TOO_SHORT FAULT VALIDATION410 VALUE_TOO_LONG FAULT VALIDATION411 ONE_IS_REQUIRED FAULT VALIDATION412 ATTACHMENT_NOT_POSSIBLE FAULT VALIDATION413 ATTACHMENT_TOO_LARGE FAULT VALIDATION414 NOT_EMPTY FAULT VALIDATION401 ALREADY_ASSIGNED FAULT VALIDATION500 APPLICATION FAULT APPLICATION501 NOT_POSSIBLE FAULT APPLICATION900 UNKNOWN FAULT
406:ThisResponseCodeisusedwhenoftwoormorefields,onlyoneisallowed.Youshouldalwayscheckformorethanoneoftheseerrorcodesintheresponse.411:ThisResponseCodeisusedwhenoftwoormorefields,oneisrequired.Youshouldalwayscheckformorethanoneoftheseerrorcodesintheresponse.
