Plings Input API - SOAP
From Plings Info
You can browse the methods at: http://feeds.plings.net/services/activities.php
The WSDL for the SOAP service can be found at: http://feeds.plings.net/services/activities.php?wsdl
- New: 06/08/09 New methods addActivityCategoryOfTaxonomy (and corresponding remove method) to allow submission of Categories in line with existing well defined taxonomies e.g.IPSV
- New: 28/04/09 New field added to SimpleActivity to prepare the SOAP service to accept data on behalf of other organisations/activity providers. The wsdl has the new addOrganisation method, which is now (20/05/09) documented here. Some SOAP clients will need to adapt to the new DPProviderID field in a SimpleActivity object.
Contents |
ASP.NET developers
On your SOAP client you must enable cookies. Set serviceName.CookieContainer to a new instance of System.Net.CookieContainer. See Developer_FAQ#ASP.NET_service_has_trouble_connecting_to_Plings
Methods
boolean register( string Key )
- This method should be called once, straight after web service is initialised. The string passed should be the API Key registered to the Organisation/Account that is publishing the activity.
- Please Note: 1=true,0=false on all boolean methods where applicable
integer publishSimpleActivity( SimpleActivity Activity )
- Passing an object of type “SimpleActivity” to this method will create a single occurrence of the activity. To add an activity that occurs on different days over a period of time, multiple calls to this method should be made, providing the specific dates and times of the activities occurrence.
- Returns the ID of the activity created.
string updateSimpleActivity( integer ActivityID, SimpleActivity Activity )
- When passed an ID of an activity and a “SimpleActivity” object, this method will update any details on that activity. This method will only update a single activity at a time.
- Returns true (1) on success. This call acts like a boolean method, but returns the result in a string.
- There is an additional method available on updateSimpleActivity - UpdateFuture: xsd:int - by supplying '1', you update all future activities linked to the one supplied.
string deleteActivity( integer ActivityID )
- This will completely remove data held on the activity of the ID passed to this method.
- Returns true (1) on success. This call acts like a boolean method, but returns the result in a string.
- There is an additional method available on deleteActivity - DeleteFuture: xsd:int - by supplying '1', you delete all future activities linked to the one supplied.
boolean addActivityCategory( integer ActivityID, string Category )
- To add a category to an activity, you should call this method passing the ID of the activity and the category string. see Plings_Input_API_-_XML_via_HTTP_POST#Categories for more information about the categories in use.
- Returns true (1) on success.
(new 06/08/09)
boolean addActivityCategoryOfTaxonomy( integer ActivityID, string Category, string Taxonomy)
- This functions is the same as addActivityCategory, however, it adds a first parameter 'Taxonomy'. This should be specified as taxonomy[:taxonomyId]. e.g. plings or ipsv:5569, etc. It can be a self defined taxonomy of your own making or it can be in line with local/national taxonomies. We do not perform any checking or look ups on this submitted data, so you need to be accurate.
Example_Code_SOAP#Adding_Category_and_Taxonomy.28s.29
- Returns true (1) on success.
boolean removeActivityCategory( integer ActivityID, string Category )
- Removes a category string from the activity defined by the ID passed.
- Returns true (1) on success.
(new 06/08/09)
boolean removeActivityCategoryOfTaxonomy(integer ActivityID, string Category, string Taxonomy)
- Removes a category and taxonomy string from the activity defined by the ID passed.
Example_Code_SOAP#Removing_a_Category_supplied_with_a_Taxonomy
- Returns true (1) on success.
boolean addActivityKeyword( integer ActivityID, string Keyword )
- To add a keyword to an activity, you should call this method passing the ID of the activity and the keyword to add. Keywords are a 'free tagging' facility. see Example_Code_SOAP#Adding_Keyword(s)
- Returns true (1) on success.
boolean removeActivityKeyword( integer ActivityID, string Keyword )
- Removes a keyword from the activity defined by the ID passed.
- Returns true (1) on success.
boolean addActivityECMCategory( integer ActivityID, integer ECMID )
- To associate an Every Child Matters category to an activity, you should call this method passing the ID of the activity and the ID of the ECM Category you are wanting to associate.
- Returns true (1) on success.
boolean removeActivityECMCategory( integer ActivityID, integer ECMID )
- Removes the association with an Every Child Matters category from the activity defined by the ID passed.
- Returns true (1) on success.
boolean addActivityActivityTypeCode( integer ActivityID, integer ActivityTypeCode )
- To associate a Activity Type Code to an activity, you should call this method passing the ID of the activity and the ID of the Activity Type Code you are wanting to associate.
- Returns true (1) on success.
- Please Note: This method is not really used at the moment. A full taxonomy of Activity Types is being developed for future use. You may investigate the activities method from: https://sprs.substance.coop/services/lookups.php?wsdl which is simply a collection of tags that have been gathered from various places.
boolean removeActivityActivityTypeCode( integer ActivityID, integer ActivityTypeID )
- Removes the association with an Activity Type Code from the activity defined by the ID passed.
- Returns true (1) on success.
int addVenue( SimpleVenue Venue )
- This method creates a new Venue within the system. Should the venue already exist, the ProvideVenueID (an ID that you supply from your own records) is applied to the existing venue.
- Returns a Plings VenueID on success (> 0)
- Error codes:
- -1 = No ProviderVenueID given
- -2 = Unable to locate postcode
- Please Note: This function is a duplication of the addVenue method found in the Venue API Documentation, however, documentation for this group of web services has yet to be published.
string addOrganisation (New method added 18/4/09, documentation 20/5/09)
- This method creates a new Organisation within the system. The combination of your API key and the unique id by which you reference this organisation locally, provides a unique record in our system. Organisations that you submit become 'child' organisations of you as a data provider.
- Returns a Plings OrganisationID on success (> 0)
Data Type Definitions
SimpleActivity
Please Note: a SimpleActivity cannot be created without a valid VenueID.
- The SOAP service acts in a 'programmatic' way, dealing with each request in turn. Therefore 'venues' MUST be added BEFORE 'activities' can be added.
- VenueID's can be generated by using the SimpleVenue method (below), where we try to match submitted data to the existing dataset. If a venue already exists we return the existing VenueID, if this is a new Venue to us, we issue a new VenueID.
|
SimpleVenue
|
SimpleOrganisation
(New method added 18/4/09, documentation 20/5/09)
|
Code Examples
Example Code for the SOAP methods can be found at Example Code SOAP
