SOAP API changes release 2.7

Below is an overview of changes to the SOAP API with the upcoming release of Copernica Marketing Software 2.7 on November 28. If you prefer an overview of just the added, removed and changed API Calls, please check the special overview page.

Specific WSDL versions are now always available

The definition of the SOAP API is stored in a WSDL file. For every new release this WSDL file is a little different, and when we discover bugs in the WSDL file, we may even make tiny changes to the WSDL file on the live server. For most applications, this is not a problem, because they can handle those changes in the WSDL file.

However, some applications do not handle this well, and we have added a new feature to the application to solve this. With the new version of the software it is possible to use a cached WSDL that does not change in between versions, and that will not have any bugs fixed in them. If you use this version of the WSDL file, you do not have to worry that the file is suddenly changed.

The WSDL version can be requested with the following url: http://yoursoftwaredomain.com/?SOAPAPI=WSDL-2.7, to get the initial WSDL file of release 2.7 of the application, that will remain unchanged forever.

Conflicting SOAP API parameters have been fixed

Due to a mistake in the software, a couple of methods in the WSDL had two ID parameters. This is of course not possible - two parameters with the same name can not be distinguished - and thus we had to make some changes to the SOAP API. We have renamed one of the ID parameters to a parameter called 'identifier'.

The following methods are affected:

* input_account_webformfollowup
* input_collection_constraint
* emailingdocument_litmusTest
* emailingdocumentlitmustest_spamResult
* litmusemailtestresult_resultimage
* litmuswebtestresult_resultimage
* partcondition_field
* partminicondition_field
* user_rssarticle
* website_session

After this change, the 'id' parameter represents the id of the object that is on the left side of the method, and the 'identifier' represents an object for the right side of the method. For example: In the case of 'partcondition_field', the 'id' parameter identifies the 'partcondition', while the parameter 'identifier' identifies the field that is retrieved.

Although in theory this change affects all SOAP API applications that were using one or more of the methods mentioned above, but we do not think that such scripts exist, because we have not received any complaints about conflicting parameters.

ID parameter no longer required for SOAP API Account_* methods

Most SOAP API methods require at least one ID parameter that specifies the object on which the operation is performed. For example: the EmailingTemplate_createDocument method requires an ID parameter to identify the template on which the document should be based and the method Database_createProfile needs the ID parameter for identifying the database. The general rule is that the ID parameter identifies the object of the first part of the method name, the part before the underscore. This ID parameter is not only required by the two example methods described above, but by hundreds of different API calls that the application offers.

For methods that work on the Account object, for example the methods Account_createDatabase and Account_createEmailingTemplate, this ID parameter was also required to identify the account in which the database should be created, or whatever call you want to do on the Account object. This was a littlebit strange, because it is only possible to change and retrieve data in your own account. Thus: if you specify the ID of any other account than your own, the Account_* method will send back an error. Hence, the ID parameter is not variable at all and you are obliged to always send the ID of your own account.

So the question was raised why we do require that ID parameter to Account_* calls, if it is not variable. This was a good question and we have decided to remove this parameter from the SOAP API. Starting with version 2.7, all Account_* methods of the SOAP API no longer need the ID parameter. If you still send this parameter with your calls to the API, it will be ignored. This will make working with the SOAP API more straightforward. This also means that when an account object is retrieved the result contains no ID field.

SOAP API updated for mailing conditions and date conditions

There are 3 types of mailing conditions that you can define for your selections or mini selections: email, fax or sms.

These offer the options to select profiles/subprofiles that received (or did not receive) a document in a specified time period. For this, the classes Email(Mini)Condition, Fax(Mini)Condition and Sms(Mini)Condition offered properties to retrieve and set: two dates (afterTime, beforeTime) and a DateMutation property (mutation). Now, the mutation property is not supported any more, but we introduced two new properties: afterMutation and beforeMutation.

These two define the interval in which you require the document (or more documents) to be sent to the profile/subprofile. afterTime is the time after which you require the document to be sent. BeforeTime is the time before which you require the document to be sent. If you have a fixed time for your condition, set it by updating the property afterTime or beforeTime to a timestamp. If any of those is not fixed, but depends on current date, you can set the properties afterMutation or beforeMutation to specify how this date should be computed depending on current date.

The Date(Mini)Condition was modified in a similar manner. It offered the option to filter your profiles/subprofiles based on a datetime field, a mutation object and another fixed date. The mutation would be applied to the date found in the specified field and it would be compared to (depending on your selection, before or after) a fixed date or current date. The properties for these were: mutation, comparison and date. All these properties are no longer supported. We have improved date conditions: they now offer, like mailing conditions, an interval in which you can require the selected field to be. These dates can be fixed by setting the properties afterTime or beforeTime, or they can be computed depending on current date, by using two the properties afterMutation and beforeMutation.

Added option to escape HTML code

We've added a new option that will allow automatic HTML code escaping from templates, documents, web pages and webforms. This option is available either via SOAP API either via the application interface. In the application interface you can find this feature along with language and time zone settings for the document/template that you are editing. The default status of this feature is 'on' (active) for newly created documents and templates and 'off' for existing ones.

Method to retrieve HTML source via SOAP API has been changed

Up to now, the source of a HTML document was a property of an object. The following classes all had this source property:
* EmailingDocument
* EmailingDocumentSnapshot
* WebDocument

There was a problem with these properties: the links in the source code to images or to files or the hyperlinks to other pages were not consistent. This was especially a problem for snapshots, in which some links were replaced by a numeric identifiers surrounded by ###, %%% or ~~~ symbols, while other links only contained the name of an image or a hyperlink, or were even completely missing from the source.

We also had feedback from various users that they all wanted to have a different type of returned value. Some users were not interested in the ID's or the linked elements (like the ID's of the images), but just wanted the actual source with working hyperlinks to the image server, while others wanted all links to be numeric identifiers.

We have solved this issue by removing the property 'source' from the SOAP API. As a replacement of it, there are new SOAP API methods, named EmailingDocument_source, EmailingDocumentSnapshot_source and WebDocument_source. These methods can be called with a parameter 'links' that describes what the links in the returned source should look like. The 'links' parameter can have one of the following three values:
* 'links': include links to the picserver for all images, files and hyperlinks
* 'names': include the names of all images and files, and the original urls of the links
* 'ids': include the id's of all images and files and hyperlinks

This new system is more powerful than the old one. However, this also means that you will have to update your SOAP scripts. If you have a SOAP script that was retrieving the source code of a HTML document or snapshot, you need to add an extra call to the ObjectName_source method (e.g. EmailingDocumentSnapshot_source).

Option to include sample code when creating an XSLT or a stylesheet

When you create a new stylesheet or a new XSLT in the application, you now have the option to include example code in these new objects. The example code that is included is the same code that is normally used by the application when no stylesheet/xslt is configured by the user.

The SOAP API has also been slightly changed. The methods Account_createStyle and Account_createXslt now also support a usedefault parameter. The parameter defaultxslt is no longer supported by the Account_createXslt method.

Creating or modifying database fields

To better handle databases and collections with a large number of fields we have changed the default size of fields from 255 to 50. This also applies to the SOAP API. This change allows for creating databases or collections with over 400 fields.

When creating or modifying database fields it is no longer possible to create more then 64 indexes or to exceed the maximum combined row length. This also applies to collections. Attempting to do so will result in an error and the field or index will not be created.

New service in partner progam

Since release 2.7 it is possible to search for 'data validation' partners in the partner program dialog. The partner program dialog is accessible via the help menu and it opens a tool to search for Copernica partners who can help with making templates, sending mailings, creating SOAP API scripts and so on. After this change users can now also search for partners who can help them with data validation and optimisation.

Error page added to admin module

An error page has been added to the admin module. Here you can view errors which occur without user interaction. These can be for example errors with import/exports, mailings, rebuilds, SOAP API calls. The errors can be cleared by using the 'Clear errors' button on the bottom of the page.

SOAP API *_destroy commands are no longer accessible

All the *_destroy commands that were available via the SOAP API are removed from the system. This is because those methods may only be used internally, and not from outside scripts. Use the *_remove commands instead. Users who make use of the SOAP API should check if their scripts do not have any calls to *_destroy methods in them, and replace them with *_remove before version 2.7 of the application is active.

Copying websites

We have introduced the option to copy an entire website with all pages in it in a single operation. This option is available in the web module.
For SOAP API users, there is an extra method to copy a website: Website_copy.

Access rights accessible via SOAP API

Up to now it was not yet possible to retrieve and update access rights via the SOAP API. This has been fixed. To retrieve accessrights for an object - for example for an EmailingDocument - call the SOAP API method EmailingDocument_privileges. This will return an object with a rights property holding a comma seperated list of all access rights for that object.

Access rights can also be updated. This should be done with the Privileges_update method.

For this feature there is also a method 'newDocumentPrivileges' added to the template. This method contains the rights for new documents that are based upon the template. When a new document is made from the SOAP API, then the rights are copied from the template's NewDocumentPriviliges to the document's privileges.

Personalizing objects with the SOAP API

When retrieving objects via the SOAP API, you can also request a personalized version of the object. This is not possible for all objects, but objects like an EmailingDocument, an EmailingDocumentSnapshot, a WebDocument and a number of other objects can be personalized.

In the versions up to 2.6 this could be done by supplying the parameter profile or subprofile to the methods for those objects. For example, if you called the SOAP API method EmailingDocument_retrieve with sending the profile parameter, you received all properties personalized. You could also optionally send the parameter timestamp with the call, to personalize a document as if it was a moment in the past.

But sometimes these parameters conflicted with similarly named parameters that were also required by some function. For example, the method EmailingDocument_createEmailing accepted a parameter profile as a possible destination for the mailing, but this parameter was also accepted for personalizing.

In versions 2.7 we have been renamed the parameters, to make sure no conflicts will arise. The names are now personalize_timestamp, personalize_profile and personalize_subprofile. If you use the old way to retrieve a personalized object, you must change this to the new parameters as soon as your environment is upgraded.

Selecting profiles or subprofiles based on survey status

It is now possible to make selection of profiles or subprofiles that have not submitted a certain survey or any survey. In the past it was only possible to make selections of profile who did had submitted a survey, but not yet to inverse such a selection. This feature is now also available.

This change is also available throught SOAP API and the following options have been added to the property submitter of the SurveyCondition and SurveyMiniCondition objects.
* none - this is used to select (sub)profiles who didn't submit the survey(s)
* noprofile - this is used to select (sub)profiles who didn't submit the survey(s) for a profile but who might have submitted it for a subprofile
* nosubprofile - this is used to select (sub)profiles who didn't submit the survey(s) for a subprofile but who might have submitted it for a profile

Option to disable a webpage

An option to disable a webpage from a website has been added. This feature will allow users to disable a page at any time and show an error message instead.
The feature is also accesible using SOAP API using the enabled property of a WebDocument object.

Time internationalization

All times and dates in the application are now displayed according to the personal timezone setting of the user who is working with the application. You can select a different timezone using the link in the main menu. The default time zone is based on the location of the IP address you use to access the application.

This is an important change since previous versions of the application, when all times and dates were displayed in Central European Time, i.e. the time in Amsterdam. In the past, when you were working with the application from a location with a different timezone, you had to think about this whenever you were scheduling mailings or other events: those mailings had to be scheduled for the time in Amsterdam, and not for the local time. This is no longer necessary: the times and dates in the application are now displayed according to your local timezone settings.

Important change to the SOAP API

We have also changed the way the SOAP API handles times and dates. In the past all times in the SOAP API used the Central European Time, but we have changed this to UTC. All object properties that hold a timestamp, and all methods that either accept a timestamp or return one, use UTC times. This means that for SOAP API users all times are now one hour earlier than before. Keep this in mind when you're using the SOAP API to schedule mailings or other events!

New properties for content feeds

A content feed now also supports the properties 'created' and 'modified'. These properties hold the timestamp when the feed was created, and when it was last modified. The properties can be retrieved using the SOAP API.

Files in feeds and layouts

Object that can contain HTML source code, can be linked to files and images. For example, a template for webpages can be associated with a list of images that can be used inside the template, and a list of other files (scripts, stylesheets) that can also be loaded from the template. However, for articles in a content feed and for layouts (a layout holds the HTML code for the menu on top of the application), it was up to now only possible to associate them with images, but not yet with other files like scripts and stylesheets.

This has been fixed. When editing a feed article or a layout, we are now also able to upload files to use in our content body. Under the feed and layout menu, there is an option called 'Files and images'. This option enables us to upload files from the local disk and use them inside the content body, by adding them as source inside the html tags we use (img, script, etc.).

We have also introduced a number of new SOAP API methods to manage the files for the articles and the layouts.

New error category for mailings

When the application sends out mail, it takes a number of steps to deliver a message. It starts with resolving the IP address of the destination server, then it makes a connection to that server, does some communication and delivers the mail. Things can go wrong in all of these steps. In the statistics for a mailing you can see exactly in which step errors occurred.

We have introduced a new step in the sending process. The data for an e-mail is now loaded in a separate step. First the connection is made and only when the connection succeeds and the destination address is accepted by the receiving mailserver, we load the actual e-mail from the database. In extremely unusual situations, loading this data may fail.

In the user interface of the application, on the 'errors' tab for the statistics of a mailing, we have introduced the error category 'Error getting email data from the database'. This error category is also available when making selections based on e-mail results. Because it is highly unlikely that things go wrong in this step, we do not expect a high number of errors in this category.

In the SOAP API this new error category - called no data - is also available, for example in the ProcessedEmailing_errors method and in the requiredresult property for EmailCondition and EmailMiniCondition objects.

Changes in list-unsubscribe

In the SOAP API there is no longer a unsubscribeHeader option available for the EmailingSettings, ProcessedEmailing and ScheduledEmailing classes. The classes EmailingDocument, EmailingTemplate and EmailingDocumentSnapshot have been extended to now include this property.

Priority indicator in SOAP API

In the user interface of the application, it was already possible to set the priority indicator for an e-mail document and an e-mail template. This is the setting that specifies if the mail should be marked with a little 'high priority' flag in an e-mail client.

However, for no specific reason at all, this property was not accessible via the SOAP API. This omission has been fixed. Now you can retrieve and set the priority indicator property via the SOAP API. The property is available through calls to EmailingTemplate_retrieve, EmailingTemplate_update, EmailingDocument_retrieve, EmailingDocument_update and EmailingDocumentSnapshot_retrieve.

Activating and deactivating articles in a content feed

When an article in a content feed is inactive, a yellow notification bar is displayed above it. This yellow notification bar used to only contain a warning about the article not being active, but we have now added a hyperlink to the warning. When this hyperlink is clicked, the article is activated with immediate effect, without the need to open a dialog for activating it. This will make working with feeds more easy, as less steps are required to add and activate articles.

SOAP API users who call the ContentFeedEntry_active method should take care of the following. In the past this method did not respect the 'activeFrom' and 'activeUntil' settings of the article. It could return true even when the article was not active at all because the current time was not between the set timestamps. This has been fixed, but might break SOAP API scripts that already worked around this bug, or made use of this bug.