Magic Software
Lesson 14Hands-on · ~30 min

Adding a Customer

Web services are the universal language of inter-application communication. In this lesson you'll publish Magic xpi as a Web service provider so the outside world can ask it to add a customer — the missing piece in the human-intervention scenario you started in Lesson 12.

Web Services and Systinet

Web services are described by a WSDL — an XML contract listing the available operations along with the input and output structure for each. Magic xpi can consume Web services and expose itself as one. The provider side is implemented through Systinet Server for Java, which ships with Magic xpi and supports SOAP 1.1/1.2, WSDL 1.1, JAX-RPC, JAXM, SAAJ, JWSDL, WS-Security, WS-Reliable Messaging, and WS-Addressing.

Systinet creates three Start menu shortcuts:

  • Start — runs the Systinet server.
  • Stop — halts it.
  • Systinet Enablement Server Administration Console — opens the admin UI.

Start the server before using it (Start menu, Windows service, or %WASP_HOME%\bin\serverstart.bat). The console is at http://localhost:6060/admin/console; default credentials are admin / changeit.

Exposing Magic xpi as a Provider

Magic xpi supports two Web Service modes:

Web Services ClientConsumes a published service.
Web Services ProviderPublishes Magic xpi as a service that other apps can call.

To expose a service you'll create a resource, a service definition, and an operation:

  1. Add a Web Services Server resource named AddCustomer. Leave the Systinet defaults.
  2. Add a Web Services service named AddCustomer — same name as the resource for clarity.
  3. In the service settings, set Web Service Provider to AddCustomer (the resource) and Web Service Name to AddCustomerWS — the deployed name external clients will see.
  4. Click Operations to define one or more operations on the service.
Two names, two purposes. The Service name in the left pane is internal to Magic xpi. The Web Service Name field is the name external systems use after the service is deployed to Systinet.

Defining the Operation

An operation has one return value and any number of arguments.

  1. Click Add in the Operations dialog. Name the operation Add_customer.
  2. Add an argument named RequestID, direction In, type Numeric (size 5), XSD type xsd:int.
  3. Click OK.
  4. Click Management, then Generate — this generates and registers the service inside Systinet.
Numeric vs. xsd:int. Numeric is the Magic xpi internal type; xsd:int is the type emitted on the wire in the WSDL.

The Web Service Trigger

Now build the flow that runs when the service is invoked:

  1. Create a flow named Add Customer; move it above Check Item for clarity.
  2. Add flow variables: F.RequestNum (Numeric 5), F.RequestXML (BLOB).
  3. Drag the Web Services utility into the Triggers area; name it Add Customer by WS. Magic xpi auto-selects the AddCustomer service.
  4. Open the trigger configuration. Pick the Add_customer operation; map the RequestID argument to F.RequestNum.

Retrieving the Request from the ODS

Earlier you stored the request in a dynamic ODS keyed by request number. Pull it back out now:

  1. Add a Flow Data step named Get request XML file from ODS as the first step in the flow.
  2. Action Update, type Flow, name F.RequestXML.
  3. Update Expression: ODSGet ('Request_' & Trim (Str (F.RequestNum, '5')), 1, 'B', 1).

That single function call pulls the BLOB you saved in Lesson 10 back into a flow variable.

Adding the Customer to the Database

Use a single Data Mapper step with two database destinations to insert into both Customers and Contacts:

  1. Add a Data Mapper as a child of the previous step; name it Add Customer to DB.
  2. Source: an XML source named Get_Customer_Detail; XSD course_data\schemas\request.xsd; Source Type Variable; variable F.RequestXML.
  3. Destination 1: Database destination named Add_To_Customers; Insert; Customers table; all columns.
  4. Destination 2: Database destination named Add_To_Contacts; Insert; Contacts table; all columns.

Map the columns:

Customer_IDCustomers.CustomerID, Contacts.CustomerID
Customer_NameCustomers.CustomerName
country, city, street, zipCustomers.CustomerCountry / CustomerCity / CustomerAddress / CustomerZipCode
RequestTotalCustomers.CustomerCredit
ContactID, ContactName, Contact_eMailContacts.ContactID / ContactName / ContactEmail

Testing the Web Service

Use the Systinet console to invoke the deployed service:

  1. Save the project and build the executable; start the Magic xpi Server.
  2. Browse to http://localhost:6060/admin/console and log in with admin / changeit.
  3. Locate the deployed service in the list and scroll to the Invocation Console section. Click it.
  4. Click the hyperlink for Add_Customer (), enter a request number in RequestId, and click Perform call.

The Add Customer flow runs, fetches the saved request payload from the ODS, and inserts the new customer.

Exercise

Add an HTTP entry point too.
  1. Add an HTTP trigger to the Add Customer flow that accepts the request number. Add a flow variable F.RequestHTML (BLOB) and bind it to the trigger's return value.
  2. Return a confirmation HTML page (use CustomerAdded.tpl) by updating F.RequestHTML.
  3. Mark the customer as existing in the Requests table — the existence flag is still set to false.
  4. Run the project, open the request-status HTML page from Lesson 12, and click the customer-name hyperlink. The add_customer endpoint should run end-to-end.

Summary

You should now be able to:

  • Expose Magic xpi as a Web Service provider by combining a Web Services resource, a Web Services service, and one or more operations.
  • Use a Web Service trigger to drive a flow.
  • Retrieve previously stored data from a dynamic ODS using ODSGet.
  • Insert into multiple database tables from a single Data Mapper step.