Introduction
Thank you for choosing to work with Higher Logic Thrive Marketing Professional (Thrive Marketing Professional) on this integration project! We are looking forward to a successful technical relationship with you and your company.
This article helps you to get set up and to develop your Thrive Marketing Professional Web Service.
Suggested Uses
The main anticipated use of the Web Service is to simplify the synchronization of data between Thrive Marketing Professional and another client application. This facilitates the easy transfer of email addresses captured in one environment and then being directed into Thrive Marketing Professional.
In addition to email address, other information about the email recipient can be transferred. For example, first name can be provided so that a mailing can be personalized using that data. Further segmentation of the subscriber base can also occur in Thrive Marketing Professional leveraging this personal information.
Equally important as getting information about those who wish to receive mailings from your organization is to know those people who do not wish to receive mailings from your organization. Lists of unsubscribers can also be sent to Thrive Marketing Professional so that these email addresses can be excluded from future mailings.
Aside from data synchronization, these lists can serve as a starting point for generating reports. There are many GridRequest actions that can be used to retrieve data from Thrive Marketing Professional. This included information about subscribers as well as the results of any mailing publishing.
Technology Overview
Thrive Marketing Professional has embraced a document-centric approach to SOAP-based web services. This is considered to be a "second generation" approach for web services. There are a number of benefits to this approach that we think will be helpful to you as you develop your integration. Please go to http://www.ibm.com/developerworks/webservices/library/ws-docstyle.html for more details.
These benefits include:
- Sending a single document (as opposed to making multiple iterative method calls)
- Listening for only the data that you want in a Response Document
- Avoiding RPC, which is more "fragile" with regard to versioning
Support
Understanding how Thrive Marketing Professional works will be helpful to you as you begin work on this project. The Informz Partner Relationship Manager will schedule a session, or sessions, for your team to learn about Thrive Marketing Professional and how it operates. Having a basic understanding of the Thrive Marketing Professional user interface will help you to test your API.
If you have any questions about working with this API, contact Higher Logic, support@informz.com is monitored for any technical questions related to use of the web service. Please list your name and include any relevant uncompressed XML calls in your message.
Setup
Below, you'll learn about the steps and processes needed to set up API development with Thrive Marketing Professional.
Assumptions
Thrive Marketing Professional assumes our partner’s developers have: i) a working knowledge of web services and ii) a working knowledge of XML.
Setup
Below are the steps you’ll need to go through to set up your environment to work with Thrive Marketing Professional:
- Ensure that your firewall will allow a connection to Thrive Marketing Professional’s web service.
- You will need to provide us with a list or range of IP addresses that your API requests will originate from. We will add those to a list of allowed IP addresses during the brand creation process.
- Get your Thrive Marketing Professional brand ID and brand name from Higher Logic.
- Decide if you will employ encryption.
- If no, then a user name and password will be established in the brand
- If yes, Higher Logic will provide you with an encryption key
Test Environment
You will be able to test your work via our publicly available interface at https://partnertest.informz.net/aapi/InformzService.svc.
Moving to Production
After development and testing are complete, move the work to production. Here are the steps you will have to perform to do this:
- Change the endpoint url to point to
- For the US: https://partner.informz.net/aapi/InformzService.svc (rather than partnertest)
- For Canada: https://partner.informz.ca/aapi/InformzService.svc
- Create user account in Thrive Marketing Professional if this is different than what was used during development. This can be done either by a single Thrive Marketing Professional account used for all calls, or existing user credentials can be passed in to support auditing of the messages.
Schema and WSDL Locations
The Thrive Marketing Professional XSD can be found at http://partner.informz.net/aapi/schema/InformzService.xsd.
The WSDL can be found at https://partner.informz.net/aapi/InformzService.svc?WSDL.
API Method
There is a single method in the API. This is:
PostInformzMessage (string)
The input string parameter should be a fully formed XML document.
Documents
Higher Logic provides two documents for your use:
ActionRequest - Use this when you want Thrive Marketing Professional to perform an action, such as CreateMailing or ScheduleMailing.
<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/">
<Brand id="9999">Test Brand</Brand>
<User>testuser</User>
<Actions>
[Action Details]
</Actions>
</ActionRequest>
GridRequest - Use this when you want to return tabular data from Thrive Marketing Professional. This could be a list of mailings in Thrive Marketing Professional or a list of who opened a particular mailing.
The GridRequest document retrieves information from Thrive Marketing Professional for use in the partner application. The <DataElement> node provides flexibility to request any available information using the same document format.
<GridRequest xmlns="http://partner.informz.net/aapi/2009/08/">
<Brand id="9999">Test Brand</Brand>
<User>testuser</User>
<Grids>
[Grid Details]
</Grids>
</GridRequest>
All documents need to include the Brand ID, Brand Name, and User. Brand ID and User will be validated when the document is received. The Brand ID will be validated against the IP address stored with this Brand to ensure that this is a valid origination point for the brand. User will be validated against a "known" user list in Thrive Marketing Professional.
Brand name is used for logging purposes only.
Case Sensitivity and Order
The document tags are case sensitive. Make sure that the case sensitivity is respected between the calling application and API. For example, <BulkUpload> would be correct but <bulkupload> would not be. However, the comparison of string values in a grid request is case insensitive.
The order that nodes are presented within an XML document are determined by the XSD. Use the example messages provided as well as the graphical depiction of the XSD to ensure that the node order in the documents being submitted to the API match the order as found in the XSD.
Compression
All messages to and from the Web Service are compressed to help speed transfer and to reduce the amount of bandwidth needed to handle requests. The service uses standard gzip libraries provided with .NET to compress the payload of the message. The payload nodes are the ActionRequest for action messages and the GridRequest node for grid messages (reports). For the response messages, the ActionResponse and the GridResponse nodes will be also be compressed. Only the payload is compressed because the remaining header nodes are used for validation of the incoming request before decompression and decryption.
Encryption/Authentication
The web service can encrypt incoming and outgoing messages. Encryption is implemented using TripleDES encryption using 192 bit symmetric keys. Only the payload of the message is encrypted.
Using encryption for message security is strongly recommended. If implementing encryption is not an option, authentication must be implemented by including a Password node along with the User node. These values are passed "in the clear," so it is not secure.
The XML encryption technique is W3C compliant. Thrive Marketing Professional is capable of encrypting either an entire XML document or specific nodes within the XML Doc. Thrive Marketing Professional supports TripleDES (with 192 bit key).
If implementing encryption is not an option, authentication can be implemented using username and password.
Encoding
After compressing and or encrypting your payload, the data must be Base64 encoded. The example below shows the resulting message:
<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/"> <Brand id="9999">Test Brand</Brand> <User>testuser</User> <Password>password</Password> <Actions>+AUAAB+LCAAAAAAABADtvQdgH...T+oAkh/+AUAAA==</Actions> </ActionRequest>
Header Tags
Every action request contains this information. The Brand tag corresponds to a Thrive Marketing Professional brand. Within the tag there is an ID attribute that will need to match to the Thrive Marketing Professional brand’s ID to be permitted in through the web service. The User tag corresponds to a valid Thrive Marketing Professional user.
<Brand id="9999">Test Brand</Brand> <User>testuser</User> <Password>password</Password>