To make your CL-CEC useful in the IVO, you must register, in an IVOA-compliant resource registry:
The application registrations state the interfaces of the applications. The service registration states the service endpoint (the URL for access) and lists the applications that the CL-CEC can run. For each registration, you prepare a resource document (an XML file) stating the necessary metadata in a machine-readable format.
If you are setting up your CL-CEC to run applications already defined and published in the VO, then you do not need to write or publish resource documents for these; you still must write and publish the resource document for the service itself. Instead, you could look up the application resources already in the registry and quote the identifiers for these when writing the resource document for your service.
If you do this, you are declaring your service as a mirror of the existing services running the applications in question; you are promising that your service will produce the same results as those services for given inputs. The AstroGrid UIs and workflow agents will then distribute jobs indiscriminately between the services mirroring the application. Mirroring is very valuable to the IVO for load balancing and high availablity, but please don't publish your service as a mirror of an application unless you are sure that you have installed the right version of the application!
At present, you have to write the resource documents yourself. There are facilities in the CL-CEC that try to register on your behalf but they don't work properly. Do not use the "register" command from the menu! It makes an improper registration using an obsolete format. Do not derive the resource documents from the "view VO description" command on the menu! This shows you resource documents in an obsolete format.
The easiest way is to copy existing resource-documents and alter the details to suit your site. You can start with these:
These are the elements that you should check and possibly change in the application registration.
| XML Element | Usage |
|---|---|
| title | Name your resource. The title is for human readers and is shown by the resource registry in lists of resources. |
| shortName | As for title, but limited to 16 characters. For use in compact lists/tables of resources. |
| identifier | Put the unique IVO identifier (IVOID) for your application. See below for a discussion of IVOIDs. |
| publisher | Name your organization. If your organization is registered as an IVOA resource, add an attribute named ivo-id whose value is the organization's IVOID. |
| date | Set this to the release date of the underlying application programme. |
| contact | Change this to the details of the contact person for the application. |
| subject | Change this to a list of keywords relevant to your application. The IAU thesaurus is the preferred source. |
| cea:ParameterDefinition | Make one of these for each parameter, input or output, of your application. Delete the ones from the example. |
| ceab:input | Add one ceab:pref for each input parameter of your application. Delete the ones from the example. |
| ceab:output | Add one ceab:pref for each output parameter of your application. Delete the ones from the example. |
These are the elements you should check and possibly change in the service registration.
| XML Element | Usage |
|---|---|
| title | Name your resource. The title is for human readers and is shown by the resource registry in lists of resources. |
| shortName | As for title, but limited to 16 characters. For use in compact lists/tables of resources. |
| identifier | Put the unique IVO identifier (IVOID) for your service. See below for a discussion of IVOIDs. |
| publisher | Name your organization. If your organization is registered as an IVOA resource, add an attribute named ivo-id whose value is the organization's IVOID. |
| date | Set this to the release date of the service. |
| contact | Change this to the details of the contact person for the service. |
| subject | Change this to a list of keywords relevant to your service. The IAU thesaurus is the preferred source. |
| accessURL | Edit this to reflect the address and context path of your service. The value should end in /services/CommonExecutionConnectorService. If your service uses a proxy, then see the notes below. |
| cea:ApplicationReference | Add one of these for each registered application offered on your CL-CEC. The value must be the IVOID of the application's registration. Delete the one from the example. |
IVOID stands for International Virtual Observatory Identifier. An IVOID is a unique identifier for a resource document in the registry; all resource documents must have one. You have to generate suitable IVOIDs for your applications and service. It is important to get the IVOIDs right; your CL-CEC will not be usable otherwise.
An IVOID is usually written as a URI with the scheme "ivo". The part between the slashes is the authority identifer for the registry where you publish your resources. Therefore, you will have to choose a publishing registry and find out its authority before you can complete the resource documents. The part after the slash following the authority identifier is called the resource key. You choose this part.
If your service is on a port other than 80 or 8080, then you will need to run a proxy service to make your CL-CEC visible to all parts of the IVO. The convention in AstroGrid is to configure an Apache web-server on port 8080 to pass the service requests through to Tomcat. If you use this method, then the apparent public address of your CL-CEC is the address of the proxy server. You should put this address and port-number in the accessURL element of the service registration.
The following instructions apply only if you are registering in a registry built from AstroGrid components. The controls for other registry implementations will be different.
Checking the "validate" box tells the registry service to reject any resource documents that are not valid against their XML schema. Clearing the box tells the registry to accept any XML, valid or not. Invalid registrations, even if only small details are wrong, stop the system from working correctly, so you should always validate.
If the registry rejects your registration, you probably need to correct some small details in the document and to try again. If the registry complains about an authority "not managed in this registry", then you have probably mis-typed the identifer element in the document. Other points to check are the use of literal >, & and < characters in the text; XML requires you to write these as >, & and < respectively. You should also check that you have closed the quotes on any XML attributes you have edited.
If you want to cease service of an application, then you should update the list of managed applications in the service registration of your CL-CEC. You can do this be editing the resource document on local disc and re-registering it, as described above, under the same identifier.
If you want to withdraw your CL-CEC from service permanently or for a lengthy period (but not just for short down-time), then you should deregister it. You do this by editing the service resource-document, changing the value of the status attribute on the Resource element to "deleted" and re-registering it, as described above, under the same identifier.
If you want to cease service of an application, and if that application will never again be served by any CEC, then you may deregister it. The deregistration process is the same as for a CL-CEC service, described above.
User's Guide
Installer's Guide
Developer's Guide