Configure a custom order submit integration job

23 min

You can create an order submit integration job to submit orders from Optimizely Configured Commerce to an ERP. The ERP then handles order fulfillment.

Many submission jobs use an API provided by an ERP, so it is crucial that you know how to use the API before continuing. Talk to your developer or partner for help.

This job uses the GenericSubmit preprocessor, a custom integration processor, and the ProcessSubmitResponse post processor. The GenericSubmit preprocessor retrieves a customer order and related data from the Configured Commerce database using an order number. The custom integration processor submits customer orders to the ERP through the API. The integration processor also creates a result data set with the ERP order number, which is returned from the ERP after submitting the customer order. The ERP order number links the customer order in Configured Commerce with the customer order in the ERP. The ProcessSubmitResponse post processor takes the ERP order number from the result data set and update the customer order in the Configured Commerce database.

Prerequisites

Install the WIS on your local computer

Create the FakeERP application

First, you will create the FakeERP application. This application will have an API with an endpoint for submitting an order. This endpoint will be available at /api/order using a POST request. This application will be an ASP.NET Web API application. You do not need to know how this type of application works. You just need to know how to run it within Visual Studio.

Open Visual Studio.

Create a new ASP.NET Web Application named "FakeERP".

Select the Web API template.

In the Controllers directory, add a new, empty Web API controller named "OrderController".

Add the following code to the file. As mentioned before, you do not need to worry about the implementation. The application just needs to run and respond to the order submission endpoint.

public class OrderController : ApiController{    [Route(Name = "GetOrder")]    public HttpResponseMessage Get([FromUri] string id)    {        var response = this.Request.CreateResponse(HttpStatusCode.OK, new Order());        return response;    }     public HttpResponseMessage Post([FromBody] Order order)    {        // ERP processing for order         order.ErpOrderNumber = Guid.NewGuid().ToString();         var response = this.Request.CreateResponse(HttpStatusCode.Created, order);        response.Headers.Location = new Uri(this.Url.Link("GetOrder", new { id = order.ErpOrderNumber }));         return response;    }} public class Order{    public string OrderNumber { get; set; }     public string CustomerNumber { get; set; }     public string ErpOrderNumber { get; set; }}

Build the solution and run the application. This can usually be done in the Debug menu by selecting Start Debugging.

When the browser opens, copy the URL in the address bar. You will need this when you set up the integration connection.

Stop running the application. Click the "stop" icon button in the header menu in Visual Studio.

That's it! The FakeERP application is complete. It does not store the customer order anywhere because that does not matter for this walk-through. In a production environment, you will be submitting the customer order to a real ERP. For simplicity, this application returns a new Guid value as the ERP order number. You will need to run this application again later, so keep track of it.

Now that the FakeERP application is complete, you can start configuring the integration connection to the FakeERP application.

Create the integration connection to the FakeERP application

The integration connection is used to specify the URL used to connect to the FakeERP application.

Go to Administration > Connections.

Click Add Integration Connection.

Enter a Name, such as FakeERP API.

Select WebService for the Type Name.

Select the appropriate time zone for the Source Server Time Zone.

Enter the URL you copied from the FakeERP application and append api. You should end up with something like http://localhost:24443/api. This is the URL you use to make API requests to the FakeERP application.

Click Save.

If the API requires authentication, specify those credentials using the Log On and Password fields. Then, within your custom integration processor, authenticate with the API using those credentials.

Now that the connection is configured, you need to configure the WIS you installed.

Configure the WIS

Before continuing, configure the WIS with the integration connection that you just created. This lets you select an integration processor for the integration job and also lets the job be executed.

Next, you can create the job that submits the customer order to the ERP.

Create the order submit integration job

This integration job uses standard processors and a single job step to specify the OrderNumber parameter.

Configure the job details

Go to Administration > Job Definitions.

Click Add Job Definition.

Enter the Job Name, such as Order Submit. This helps indicate the job type and which Configured Commerce object it affects.

Select Submit for the Job Type.

Select the FakeERP API integration you just created for the Connection. This lets the integration processor connect to the ERP.

The Preprocessor, Integration Processor, and Post Processor fields indicate what type of work is completed by the integration job. These processors operate in the order the fields display in the form. The preprocessor does any preprocessing required for the job, including aggregating data or constructing a query for the integration processor. The integration processor builds on the work done by the preprocessor, usually operating on the data or objects retrieved or constructed by the preprocessor. The post processor processes the response from the integration processor. This can include consuming data retrieved from the ERP by the integration processor. Read more about the other preprocessors, integration processors, and post processors and their purpose.

Select GenericSubmit for the Preprocessor. This retrieves a customer order and its data from the Configured Commerce database using an order number.

Select None for the Integration Processor. You will configure this later after you create the custom integration processor.

Select ProcessSubmitResponse for the Post Processor. This takes the ERP order number from the dataset returned by the integration processor and updates the customer order in the Configured Commerce database.

Select Order Submit for the Standard Job Name. This is how Configured Commerce decides which job to use when submitting a customer order to the ERP.

Click Save.

Now that the processors and integration connection are configured, you can create the integration job step. This job step is expected by the GenericSubmit preprocessor.

Create the job step

Integration job steps provide a way to order work within a job. Each job step is executed once during the job execution in ascending order using the Sequence number. For this job, you only need one job step to specify a parameter to hold an order number. This order number is used by the GenericSubmit preprocessor to retrieve the customer order within the Configured Commerce database. The customer order is eventually submitted to the ERP.

Select the Steps tab.

Click Add Job Definition Step.

Select 1 for the Sequence. This is the first and only integration job step in this job.

Enter a Step Name, such as Submit Order. This helps others understand the step's job.

Select Cart for the Target Object. This is the type of object that is retrieved from the Configured Commerce database. Using the OrderNumber parameter, the GenericSubmit preprocessor retrieves a customer order object.

Click Save.

This job's processors do not use the Deleter Behavior and query clause fields.

Configure the OrderNumber parameter

The GenericSubmit preprocessor expects the parameters to be natural key properties on the Target Object.

Select the Parameters tab.

Click Add Job Definition Step Parameter.

Enter a Name, such as OrderNumber. The name casing does not matter. This is the name of the natural key property for the customer order (Cart) object.

Select String for the Value Type.

Click Save.

You should leave the Default Value field blank. This value is used when the integration job is executed and the OrderNumber parameter value is blank. Leaving this field blank is a precautionary measure. If the default value is an actual order number and the integration job is executed without specifying a value for the OrderNumber parameter, the customer order linked to the default value could be submitted multiple times.

The Prompt field is used to configure instructional text for this parameter. This instructional text is displayed as a form label when a user schedules this integration job manually. Leave the Prompt field blank for now. You can configure it later.

After you have configured the parameter, you need to create the custom integration processor. This integration processor will actually submit a customer order to the ERP via the API.

Create the custom integration processor

The integration processor knows how to communicate with the ERP to submit a customer order. This custom integration processor communicates with the FakeERP application you created earlier.

Open your Configured Commerce solution in Visual Studio. The Configured Commerce solution comes with an Extensions project. This is where you can place custom preprocessors and post processors. However, custom integration processors should not be placed here because they run in the WIS installed on your computer, not within the context of the Configured Commerce application. You can use a separate project for the custom integration processor.

Add a Class Library project to your solution named Extensions.Integration.

In the Extensions.Integration project, add a class named "IntegrationProcessorFakeERPSubmitAPI". If you preprend the class name with "IntegrationProcessor", that bit will be removed from the name when displaying the processor in the drop-down field in the integration job configuration.

public class IntegrationProcessorFakeERPSubmitAPI{}

Implement the IIntegrationProcessor interface. To be used as an integration processor, the class MUST implement this interface. You may need to reference the Insite.WIS.Broker library.

public class IntegrationProcessorFakeERPSubmitAPI : IIntegrationProcessor{    public DataSet Execute(SiteConnection siteConnection, IntegrationJob integrationJob, JobDefinitionStep jobStep)    {        throw new NotImplementedException();    }}

Within the Execute method, create a new IntegrationJobLogger. The job logger is used to log information to the job logs during the job execution. The job logger can log informational statements, warnings, and errors. You can view these job logs in the Admin Console at Administration > Jobs > Job Definitions > Order Submit > History. After you create the job logger, log an informational message stating that the order submission is starting.

public DataSet Execute(SiteConnection siteConnection, IntegrationJob integrationJob, JobDefinitionStep jobStep){    var jobLogger = new IntegrationJobLogger(siteConnection, integrationJob);     jobLogger.Info("Starting OrderSubmit to FakeERP API.");}

Get the initial data set created by the GenericSubmit preprocessor and validate the expected data. The preprocessor should have included a table named "CustomerOrder" in the data set to hold the customer order. You are going to use the "OrderNumber" and "CustomerNumber" from this table. There is an object named "Data" located in the Insite.WIS.Broker.Plugins.Constants namespace. This object includes values for all the data set tables and columns used during integration. You can use the Data.CustomerOrderTable value instead of directly typing "CustomerOrder" to retrieve the table.

public DataSet Execute(SiteConnection siteConnection, IntegrationJob integrationJob, JobDefinitionStep jobStep){    // ...     // You may need to reference Insite.Common to use the XmlDatasetManager.    var initialDataset = XmlDatasetManager.ConvertXmlToDataset(integrationJob.InitialData);     if (initialDataset == null        || !initialDataset.Tables.Contains(Data.CustomerOrderTable)        || initialDataset.Tables[Data.CustomerOrderTable].Rows.Count == 0)    {        // The Fatal method does not halt execution. It simply logs the information        // specifying a log type of "Fatal". This can make it easier to find important        // issues when viewing the job logs.        jobLogger.Fatal("The initial dataset is empty and OrderSubmit cannot proceed. Please verify that the GenericSubmit preprocessor is being used for this job.");        throw new ArgumentException("Invalid initial dataset");    }}

Retrieve the "OrderNumber" and "CustomerNumber" from the "CustomerOrder" table. These two values are stored in separate columns in the first row of the table. These column names are also included in the Data object, so you do not have to type the name.

public DataSet Execute(SiteConnection siteConnection, IntegrationJob integrationJob, JobDefinitionStep jobStep){    // ...     var dataRowCustomerOrder = initialDataset.Tables[Data.CustomerOrderTable].Rows[0];     var customerNumber = dataRowCustomerOrder[Data.CustomerNumberColumn].ToString();    var orderNumber = dataRowCustomerOrder[Data.OrderNumberColumn].ToString();}

For this walk-through, you have the information you need to submit the order to the ERP (you may need more depending on your specific ERP). Communication with the API will involve the JSON data type. Some of the work requires a third-party library called "Newtonsoft.Json". You can install it using the Package Manager Console and the command below.

install-package Newtonsoft.Json

After you have installed the package, you can create the request objects to send to the ERP API. This involves creating a separate Order class to hold the ERP response object. You can also create a variable to hold the ERP order number returned in the ERP response.

public class Order{    public string OrderNumber { get; set; }     public string CustomerNumber { get; set; }     public string ErpOrderNumber { get; set; }}

public DataSet Execute(SiteConnection siteConnection, IntegrationJob integrationJob, JobDefinitionStep jobStep){    // ...     var orderRequestObject = new Order { OrderNumber = orderNumber, CustomerNumber = customerNumber };    var orderRequestJson = JsonConvert.SerializeObject(orderRequestObject);     // This will hold the ERP order number returned from the API.    var erpOrderNumber = string.Empty;}

Now you need to create a client to communicate with the API. This can be done using any standard API library, like RestSharp. In this case, you can use the .NET HttpClient so you do not need to download and include another Nuget package. After you create the client, you can send the request to the /order endpoint. You can use the integration connection URL to create the absolute URL.

using (var httpClient = new HttpClient()){    var result = httpClient.PostAsync(integrationJob.JobDefinition.IntegrationConnection.Url + "/order", new StringContent(orderRequestJson, Encoding.UTF8, "application/json")).Result;    var contentString = result.Content.ReadAsStringAsync().Result;    var updatedOrder = JsonConvert.DeserializeObject<Order>(contentString);     erpOrderNumber = updatedOrder.ErpOrderNumber;}

Create the data set that will be returned. The ProcessSubmitResponse post processor expects an "OrderSubmit" table when processing a submitted customer order. The table needs to include the Configured Commerce order number and the ERP order number in separate columns, named "OrderNumber" and "ErpOrderNumber". This allows Configured Commerce to find the matching customer order and update the ERP order number. The table and columns names are also included in the Data object so you do not have to type the names.

public DataSet Execute(SiteConnection siteConnection, IntegrationJob integrationJob, JobDefinitionStep jobStep){    // ...     var resultDataSet = new DataSet();    var orderSubmitTable = resultDataSet.Tables.Add(Data.OrderSubmitTable);    orderSubmitTable.Columns.Add(Data.OrderNumberColumn);    orderSubmitTable.Columns.Add(Data.ErpOrderNumberColumn);     var orderNumberRow = orderSubmitTable.NewRow();    orderNumberRow[Data.OrderNumberColumn] = orderNumber;    orderNumberRow[Data.ErpOrderNumberColumn] = erpOrderNumber;     orderSubmitTable.Rows.Add(orderNumberRow);     jobLogger.Info($"Finished OrderSubmit for order #{orderNumber}.");     return resultDataSet;}

Now the integration processor is complete. However, it needs to be accessible to the WIS.

Build your solution.

Go to the Extensions.Integration debug directory in the file system and find the "Extensions.Integration.dll" file.

Copy the DLL and paste it into the DLL folder where the WIS will be looking to load custom integration processors. This DLL folder is configured in the SiteConnections.config file in the install directory of the WIS. On my computer, this is located at C:\\Program Files\\Optimizely\\Commerce Integration Service V4.3\\SiteConnections.config. If the WIS is already running, make sure to stop it before copying over the DLL.

Back in the Extensions.Integration debug directory, find the "Newtonsoft.Json.dll" file.

Copy the "Newtonsoft.Json.dll" file to the install location of the WIS. You will need to copy all the third-party library DLLs used by the integration processor.

After you copy over the DLLs, start the WIS.

In the same directory as the SiteConnections.config file, find the log.txt file.

Open the log.txt file and verify your custom integration processor is found and loaded. The log file appends new logs, so look near the bottom of the file.

If the integration processor is not found or loaded, check for errors in the log.txt file. Also, verify the site connection in the SiteConnections.config file is configured correctly. If you need to, go back and verify you configured the WIS correctly.

Now that the integration processor is complete and loaded into the WIS, you need to configure the Order Submit integration job to use it.

Configure the order submit job with the integration processor

Back in the Admin Console, go to Administration > Jobs > Job Definitions > Order Submit > Details.

If everything was configured correctly up to this point, the Integration Processor drop-down should now have an entry for "FakeERPSubmitAPI", your custom integration processor. Select your custom integration processor.

Click Save in the top right corner.

Now that the Order Submit job has been configured with the integration processor, you can run the job manually to verify it works.

Run the order submit job manually

Before you can run the job manually, you need to make sure the FakeERP application is running. Once that is up and running, you need to get an order number for an order so you can submit it to the ERP. Remember, you created an OrderNumber parameter earlier. To get an order number, checkout on the Storefront. On the Order Confirmation page, copy the order number. Now you are ready to run the job.

Back in the Admin Console, go to Administration > Jobs > Job Definitions > Order Submit.

In the top right corner, click More Actions.

Select "Schedule Job". A dialog will display with a form that has a field for an order number.

For the Order Number field, use the order number you copied earlier.

Click Schedule Job.

You can check the status of the job while it is running.

Select the History finger tab. Here you can see a list of the past executions of this job.

Find the most recent execution and click the View button. Here you can see the status of the execution, the parameters used by the job, and the job logs.

If the job fails, you can select the Job Logs finger tab. Here you can see the various logs that were recorded. If you notice an error log, you can click the View button again to view the error description. If you do not find an obvious error, walk back through the steps to make sure you configured the job correctly. If the job is configured correctly, but still fails, you can read about advanced troubleshooting steps to diagnose the problem.

If the job succeeds, you can verify the ERP order number was updated for the customer order. Go to Sales > Cart History and find the customer order you just submitted. On the details page, the ERP Order Number should have a new Guid value assigned to it. This order submit process will also create a copy of the customer order and use it to create an entry in the order history. This means that the order history will also have the ERP Order Number sent back from the ERP. The customer order and order history are separate objects, but may contain the same data. You can find the order history entry in the Admin Console by going to Sales > Order History. If the job fails, there may not be an entry in the order history.

The job now executes successfully. However, in many cases you may want the order submission to the ERP to happen automatically. When a user completes checkout in Configured Commerce, that order can be submitted to the ERP without your intervention. You can enable this by modifying a system setting.

Modify order submit settings

The system setting named "Submit Orders to ERP" dictates whether or not Configured Commerce customer orders are submitted to the ERP after checkout. If the setting is set to "Yes", the Order Submit integration job you just created will be executed after a user completes checkout on the Storefront. To modify the setting, go to Administration > System > Settings > Integration > Order Submit.

In order for this to work, the Order Submit integration job MUST be assigned the Order Submit standard job name. This is how Configured Commerce finds the correct job to use in order to submit the customer order to the ERP. If you followed the steps for creating the integration job, this job name is already configured so you do not need to worry. This is just a reminder of the required configuration.

Submit order through checkout

Now, you should be able to see the entire workflow in action. A user submits an order on the Configured Commerce Storefront, the Order Submit job is scheduled, the customer order is submitted to the ERP, the customer order in Configured Commerce is updated with an ERP order number. Below are a few things you can do during the workflow to verify each step is executing correctly.

After the order is submitted on the Storefront, go back to the Admin Console to verify the Order Submit job is scheduled. The job will not have a date scheduled, but there will be an entry in the History finger tab.

After the job completes, verify the status in the History finger tab.

If the job failed, check the Job Logs finger tab. The job logs may show an error that is preventing a successful execution.

Finally, you can check the customer order within Configured Commerce. In the Admin Console, go to Sales > Cart History and find the order. The ErpOrderNumber should be updated with a Guid value. Again, this order submit process will also create a copy of the customer order and use it to create an entry in the order history. This means that the order history will also have the ERP Order Number sent back from the ERP.