Lesson 11Concepts · ~20 min read

Services

Resources let other systems talk to Magic xpi; services let Magic xpi expose itself to other systems. This lesson introduces the Services section of the Settings dialog, walks you through creating an HTTP service, and explains what an endpoint is.

The Services Section

Magic xpi keeps a central catalog of the services a project exposes — the application units external systems can call. The Services section sits beside the Resources section in the Settings dialog and works the same way.

The advantages mirror those of the resource catalog:

Reusability. One definition, used many places.
Flexibility. Service definitions live in their own file — no project edit needed when you swap environments.
Ease of maintenance. Everything is in one place.

As with resources, the Services pane is split: definitions on the left, configuration on the right. Open it from Project » Settings.

Resource first. A service often connects to an external resource — in many cases, define the resource first, then point the service at it.

Service Types

Magic xpi ships predefined service types; each has its own configurable properties. The shipped definitions live in service_types.xml in the Magic xpi installation folder and apply to every project on that installation.

Don't edit service_types.xml. Just like resource_types.xml, this file is shared across all projects on the installation; modifying it is reserved for advanced scenarios.

Adding an HTTP Service

Open Project » Settings and select the Services node.
Click Add. The New Service dialog opens.
Choose HTTP from the Service Type dropdown.
Name it RequestConfirmation.
Click OK.

The HTTP service has just two properties:

Web Server	The website where the Magic xpi requester lives. Defaults to `%MachineName%` — an environment variable that resolves to the local computer name.
Alias	The website's alias. Defaults to `%Alias%`, an environment variable whose default is `Magicxpi4.5`.

Leave the defaults; you'll wire this service into an HTTP trigger in the next lesson.

HTTP Endpoints

When external code calls an HTTP service it usually needs to pass extra data — arguments, parameter names and types. Each predefined set of passed values is an endpoint. You declare endpoints once on the service definition; the calling form references them by name.

The trigger URL takes the following shape:

http://<ComputerName>/<xpi instance>/MgWebRequester.dll?appname=IFS<ProjectName>&prgname=HTTP&arguments=-A<ServiceName>%23<EndpointName>&ArgName=ArgValue

ComputerName	The host running the Magic xpi requester.
xpi instance	The alias — `Magicxpi4.5` at this version.
`MgWebRequester.dll?appname=IFS`	Constant prefix.
ProjectName	Your current project name.
`&prgname=HTTP&arguments=-A`	Constant section.
ServiceName	The HTTP service name (e.g. RequestConfirmation).
EndpointName	Your endpoint name. `%23` URL-encodes the `#` separator.

For example:

http://localhost/Magicxpi4.5/MgWebRequester.dll?appname=IFSMagic_xpi_course&prgname=HTTP&arguments=-ARequestConfirmation%23check_request_status&RequestNum=5

Sample HTML form. Tick Generate Sample HTML in the Endpoint dialog and Magic xpi writes a ready-to-use form to %currentprojectdir%\Service\<ServiceName>. Use it as a starting point for the calling page.

Exercise

Build the request-status endpoint.

Add an endpoint named check_request_status to the RequestConfirmation service.
Pass the request number as an argument named RequestNum.
Use the Generate Sample HTML option to produce an HTML page that calls the endpoint.

Summary

You should now be able to:

Describe what a Magic xpi service is, and why a central catalog matters.
Add a new service in the Services section of the Settings dialog.
Create an HTTP service and define endpoints on it.
Construct the trigger URL that an external system uses to call your service.