Outbound integration messages

What you'll be learning about:

How to modify a workflow script to make it assemble and send integration messages

You've already put together a working integration solution, so you don't really need further instruction in creating integration message schema. However, in an outbound integration solution, the kind you're setting up now, you don't just need to process the incoming dacses - your end of the solution will have to create and send the integration messages.

Integration is an automated process, so you don't actually write any dacs-es by hand: you configure a workflow script to put them together based on their dacsem, and then to send them on their way across the wire. Workflow scripts can do this because the dacsem schema not only provides the abstract description for each integration message, but also defines how its XML structure is mapped to the workflow script syntax. Whenever a mobile form or webform is submitted to the Cloud with the type of data update that you want to send along, the associated workflow script will be triggered, and get busy.

The second step, then, after writing a dacsem file is to set up a dedicated workflow script, or modify an existing one to produce the integration messages.

Define the structure of the integration messages

As always when creating a dacsem, the first step is getting to grips with the details of the data that you want to exchange. In this example solution, you'd like to inform the Rocky Jupiter ERP (Astro) about the status updates of the delivery tasks that the Mobilengine workflow solution handles. Astro will need to identify the driver who made the change, the task that was updated, details of the change, and the date of the update. These are the data fields that the sample dacsem below uses; if you're feeling adventurous, you can customize the schema with further elements or attributes:

statusUpdate.dacsem

schema statusUpdate
meta 'rockyJupiter:statusUpdate'
namespace "http://schemas.rockyjupiter.com/statusUpdate"
statusUpdate: element{
    assignmentId: attribute of type string;
    driver: element {
       userId: attribute of type string;
       name: content of type string without whitespace; 
    }
    oldStatus: element of type string
      without whitespace
      values "Assigned" "Confirmed" "Loaded";
    newStatus: element of type string
      without whitespace
      values "Assigned" "Confirmed" "Cancelled" "Completed" "Loaded";
    changedAt: element of type dtu(dtf MM "/" dd "/" yyyy " " HH ":" mm ":" ss);
}

Now that you've got the abstract shell for the integration messages, you'll need to pump it full of actual, tasty content. Content is dynamic and there's a lot of it, so you'll use workflow scripts to work the content-pump for you.

Make the workflow scripts populate and send your integration messages

As mentioned before, the dacsem files are only blueprints for the integration messages, and it's up to workflow scripts to churn out the dacs files that carry the data updates to the integrated external ERP.

However, there is no need to create dedicated workflow scripts just to populate and fire off dacses. In fact, since one form can only serve as trigger for a single workflow script, the best practice is to modify an existing script for the job. The status updates that you'd like to transfer using the dacs-es are implemented by the confirm, load, and unload workflow scripts, so it makes perfect sense to have these same workflow scripts send a dacs about the updates they implement.

Let's get cooking. Take the three workflow scripts from the mobile workflow ( confirm , load , and unload ), and transform them into server-side, integration-messager scripts:

Make a copy of all three workflow scripts. In the copies, delete the client keyword from the header: only server-side workflow scripts can send integration messages. You will still need a set of client-side workflow scripts, so don't delete the original scripts: if you remove the server keyword from their header and rename them, they will do perfectly as the client-side counterparts of their integration-ready sisters.

When you first created these scripts, you were able to make them client-and-server ones to speed things up, because you needed the identical script to first run locally, and then in the Cloud. The need to send integration messages, which client-side scripts cannot do, requires the effective separation of the two sets of scripts.
Also in the header, reference the drivers reference table: the assignments reference table only includes the drivers' IDs but not their names, which the statusUpdate messages also require.
Still in the header, reference the statusUpdate message that all three scripts are supposed to send.
Make the script create a new integration message with the .New() method, and populate it with a series of value asignments, strictly adhering to statusUpdate.dacsem.
Include the .Send() method at the very end of the script to send the integration message.

confirm_server.rfs

server program confirm_server for form taskList
using reftab assignments;
using reftab drivers;
//use the dacsem schema name
using dacs statusUpdate;
{
//you'll be referring to the new task in the reference table repeatedly,
//so it pays to put it into a variable
    var assignedTask = db.assignments.Read
        ({assignment_id:form.controlSubmit.parent.assignment_id.value}).Single();
    db.assignments.Update(assignedTask, {status:"Confirmed"});
    
    var dacsUpdate = messages.statusUpdate.New();
    var statusUpdate = dacsUpdate.statusUpdate;
    statusUpdate.assignmentId = assignedTask.assignment_id;
    var driver = db.drivers.Read({userid:assignedTask.usr}).Single();
    statusUpdate.driver.userId = driver.userid;
    statusUpdate.driver.name = driver.name;
    statusUpdate.oldStatus = assignedTask.status;
    statusUpdate.newStatus = "Confirmed";
    statusUpdate.changedAt = dtu.Now();
    
    dacsUpdate.Send();
}

The three workflow scripts essentially need the same treatment. Apart from removing the client keyword in the header, you only need to add to the scripts to make them integration-ready. The new load_server.rfs is still the most complex of the three, as it includes an if statement, but all you need to add is a single line each at the end of the if and else blocks to assign a value to the newStatus element of the integration message.

load_server.rfs

server program load_server for form load
using reftab assignments;
using reftab drivers;
//use the dacsem schema name
using dacs statusUpdate;
{
    var confirmedTask = db.assignments.Read
        ({usr:form.user.name, status:"Confirmed"}).Single();
    
    var dacsUpdate = messages.statusUpdate.New();
    var statusUpdate = dacsUpdate.statusUpdate;
    statusUpdate.assignmentId = confirmedTask.assignment_id;
    var driver = db.drivers.Read({userid:confirmedTask.usr}).Single();
    statusUpdate.driver.userId = driver.userid;
    statusUpdate.driver.name = driver.name;
    statusUpdate.oldStatus = confirmedTask.status;
    statusUpdate.changedAt = dtu.Now();
    
    if(form.controlSubmit == form.root.loadCancel.load) 
    {
        db.assignments.Update(confirmedTask,
            {status:"Loaded",
            load_type:form.root.loadDetails.Single().loadType.value,
            comments:form.root.loadDetails.Single().comments.value});
        statusUpdate.newStatus = "Loaded";
    }
    else
    {
        db.assignments.Update(confirmedTask,
            {status:"Cancelled",
            comments:form.root.loadDetails.Single().comments.value});
        statusUpdate.newStatus = "Cancelled";
    }
        dacsUpdate.Send(); 
}

It's a good idea to save the revised workflow scripts with _server appended to the file names to differentiate them from the client-side versions. For the same reason, it is recommended to add _client to the file names of the original, now client-side-only workflow scripts after you've deleted the server keyword from their headers.

unload_server.rfs

server program unload_server for form unload
using reftab assignments;
using reftab drivers;
//use the dacsem schema name
using dacs statusUpdate;
{
    var loadedTask = db.assignments.Read
        ({usr:form.user.name, status:"Loaded"}).Single();
    db.assignments.Update(loadedTask,{status:"Completed"});
    
    var dacsUpdate = messages.statusUpdate.New();
    var statusUpdate = dacsUpdate.statusUpdate;
    statusUpdate.assignmentId = loadedTask.assignment_id;
    var driver = db.drivers.Read({userid:loadedTask.usr}).Single();
    statusUpdate.driver.userId = driver.userid;
    statusUpdate.driver.name = driver.name;
    statusUpdate.oldStatus = loadedTask.status;
    statusUpdate.newStatus = "Completed";
    statusUpdate.changedAt = dtu.Now();
    
    dacsUpdate.Send();
}

Save all the workflow scripts that you wrote or modified in your solution folder. Just to be on the safe side: you now have not three, but six workflow scripts associated with the dashboard-based complex workflow, right? Three with names that end in _server, and that include the dacs-sending functionality, and three with file names that end in _client, but which stay otherwise unchanged.

That's taken care of, then. The messages are set up for the Mobilengine-to-Astro integration. All you need is the pipeline to send them through. In the next tutorial, you'll be taking care of the Mobilengine end of the piping.

Related links

Send data to client companies via integration

Implement outbound integration