Home / Syndication / Syndication FAQ

Syndication FAQ

Questions about syndication? These "frequently asked questions" are for people who take an XML syndication feed from Do-it, or who are trying to set one up.

Setting up a new syndication feed - general questions

Overview - what happens?

In a nutshell, these are the steps that happen when your site takes our syndication service and displays syndicated opportunities:

  • your website presents the user with a page where they can choose search options. This will probably be similar to our search facility http://www.do-it.org.uk//search/opportunities.
  • your web-server turns the chosen options into a URL, that it submits as a request to Do-it
  • Do-it sends one of the following responses:
    • authorisation failed
    • no matching opportunities were found
    • a list of matching opportunities
  • your web-server takes the XML and converts it into results to display to your user
  • the user can choose a particular opportunity
  • your server turns that choice into a URL to submit to Do-it
  • Do-it puts the details of the opportunity into XML and returns it
  • your web-server turns this into a page to display to your client.

Hardware - what do we need for our site?

A server with access to the internet. This may run any suitable operating system, usually Windows, Unix or Linux. Your server doesn’t have to be hosted at your premises; you may well pay a provider to host and maintain a server on your behalf.

Software - what do we need for our site?

A web server hosting a public website (or a corporate intranet), with the ability to write new HTML pages. A suitable server-side language, the most likely being Java, ASP, PHP or Perl.

Software - what to use to handle XML responses?

Most sites will process (known as parsing) incoming XML in the language that they use throughout the site, whether it be PHP, Perl, C#, Java, JSP/ASP scripting or something else. You should find adequate support for parsing XML in your language of choice.

Skills - what do we need to handle a syndication feed?

You will need a software developer who is skilled and experienced in the server-side language used on your site, and who understands how to process XML using that software. They will need to be able to write server-side code to:

  • receive web form content
  • make HTTP requests to Do-it’s web server
  • parse XML content returned
  • render results into HTML pages

Development by a volunteer - can you give me an idea of the skills/background needed?

They will need suitable knowledge of the server-side language used on your site, as above. They will need experience of developing web applications, particularly parsing XML. If they have considerable development experience, but not with the server-side language used by your site, they may be able to learn it by themselves.

Can you develop, or help me develop, our site?

We don’t get involved in helping people develop their websites. There are too many organisations and different server-side languages.

We will of course help you with any specific questions (see the section below).

Setting up a new syndication feed - detailed questions

Where is the technical documentation?

All the technical information is contained in a document called Do-it search web service user interface. You should have a copy, if not please contact us.

How does authentication work?

There are two aspects to authentication: your Origin code, and your IP address(es).

Each syndication partner is given a unique three-letter Origin code that should be quoted when submitting requests. For example:

http://do-it.org.uk/xmlOppSearch.do?Origin=[Add Your Origin Code]&Postcode=N1&Distance=5

You should be insert your own code. Origin must have a capital O.

If you try the above URL you will find that it doesn't work. That's because our server checks the IP address of the machine that has submitted the request against the known addresses for your Origin code. You must supply us with a list of your valid IP addresses so our server can ensure that requests are coming from machines that you have authorised.

How do I find our IP addresses out?

Find the IP address of the server that is submitting requests to us.

Don't run this on your own computer, except when you have your web-server installed locally (typically during development)We need to enable the IP address belonging to the server that submits syndication requests to us.

If you are developing a website on your local PC, please bear in mind that often the IP address associated with a PC is internal to your organisation. You may be behind a proxy/firewall that will have a different IP address to the machine that you are making the request from.

To be clear, we need the IP address of the proxy/firewall that will be relaying the request to us.

Your organisation may use a range of IP addresses to communicate with us, and we will have to know these if we want to accept requests from them. You will probably need to consult your internet connection/network provider.

How do I know if Do-it has refused to authorise a request?

You will get a response looking like this:

<DoItOppSearch xsi:schemaLocation="http://www.do-it.org.uk /xsd/search.xsd">
<OppsReturned>0</OppsReturned>
<ErrorCode>4 </ErrorCode>
<ErrorDescription>Unauthorised Access</ErrorDescription>
</DoItOppSearch>

How do I know if our own website is refusing to process a request?

You will not see one of our responses, like the one shown above. If it has been generated from your own software, you will see something like the following, for example:

The underlying connection was closed: Unable to connect to the remote server.

or

Error 403. Forbidden: You don't have permission to access /bla/bla on this server"

Third party developers

If you are a third party developer, creating a website for a syndication partner, you’ll need to be able to submit requests during development. These requests may well be from a different IP address to the server that will host the website.

Please contact us, so we will need to check with the organisation that you are working for. Once we have confirmed your request is genuine, we will enable the IP addresses you are using

How do I find our Unique Origin code?

Your organisation will be given this when you become a syndication partner. Please contact us if you don't know it.

Problems with queries

How do I eliminate opportunities that are irrelevant to our site?

You can use the activity and/or interest parameters to restrict the opportunities returned to just those that have been flagged with relevant values. For example, to restrict the results to opportunities with the activities of ‘Administration’, ‘Advice, Information and Support’, and ‘Architecture and Building Work’, you would add the phrase Activity=1,42,3 to the query URL.

 A full URL could be:

http://do-it.org.uk/xmlOppSearch.do?Origin=[Add Your Origin Code]&Postcode=N1&Distance=5&Activity=1,42,3

Alternatively you might want to restrict opportunities based on the interest they are flagged with. For example, if you wanted to restrict to just those opportunities that are flagged with the ’Environment’ interest, you would add &Interest=11 .

A full URL could be:

http://do-it.org.uk/xmlOppSearch.do?Origin=[Add Your Origin Code]&Postcode=N1&Distance=5&Interest=11

See the documentation, Do-it search web service user interface,  for a definitive list of activities, interests and their related codes.

Can I query availability?

On the Do-it site users are able to restrict their queries to days of the week, and whether the opportunities are available for morning, afternoon, or evening. Unfortunately, this is not available via a syndication query.

How do I control the number and size of pages returned?

The GetXResults parameter specifies a maximum number of results, and this may be split into pages using the Pagenumber and Pagesize parameters.

For example, if you wish to show the second page, with 10 results per page, out of a maximum of 50 results, use the following paging parameters in your querystring request:

GetXRecords=50&Pagenumber=2&Pagesize=10

How do I restrict queries to return only our organisation's opportunities?

If you want to restrict the results you display to just your organisation's queries, you can add a MainAccount parameter to your query, for example:

http://do-it.org.uk/xmlOppSearch.do?Origin=[Add Your Origin Code]&Postcode=N1&Distance=5&MainAccount=youthnet

You should contact us to find out what MainAccount value you should quote. There are other parameters that may be more suitable to your organisation. Please read the documentation, or contact us if you are still unsure.

How do I stop other organisations viewing opportunities we have posted?

You cannot do this. All opportunities on Do-it are made available to all organisations.

Problems with an existing feed

Once a feed has been set up it should continue to work without problems. If you do encounter unexpected results, please do contact us immediately.


Site Map | Do-it | YouthNet | About Product Support | Contact us