Create A Complex Service In D365

In a previous article we looked at how to setup Postman to call a existing D365 service. We then reviewed the steps to create a new custom service in Dynamics 365 F&S. However that was a very basic service. Finally in this article we will create a complex service in D365. Do you need to send an array, or list, of data into the system, or perhaps several different objects? In this article I will show you how.

What Are The Steps?

In order to create a complex custom service in D365, we still need the same core components of any service.

1. We need a new class that is our ‘Request‘ object. The data we send in will be mapped to the variables in this class. Then we will use this class to run our operation.
2. We need a new calls that is our ‘Response‘ object. In our code we will set the variables in this class to contain whatever information we want returned to the calling program. D365 will then convert these values into JSON data.
3. We need a Service class. This is the class where we will put the code that will: a) read the data in our Request object, b) run some process, and then c) populate the Response object.
4. We need a Service object, that points to our Service class. This lets Dynamics 365 know that our class can be called by an outside system.
5. Lastly, we need a Service Group to put our Service object into.

What is New in Our Complex Custom Service?

Let’s pretend that we have information for a sales order that is coming from an outside system, such as a website, that we want to send into D365. We can use a complex service to do that.

Before we create the other objects of the service, we will create a ‘header’ class to contain the sales order header information. And we will create a ‘line’ class to contain the sales order line information. Then I will show you how your service can use this information

Create The Header Class

In your Visual Studio project, create a new class by right clicking on your project, and selecting ‘Add item’. Then select ‘class’ from the list, and selecting ok. In my case I am going to create a very simple class with just a few variables. Remember to include the [DataContractAttribute] attribute above your class. And use the [DataMember(“<name of your field>”] attribute on each parm method. I named my class ‘rsmTutOrderHeaderClass’, and it looks like this:

[DataContractAttribute]
public class rsmTutOrderHeaderClass
{
    private str messageId;
    private str salesOrderNumber;
    private str customerAccountNumber;

    [DataMember("MessageId")]
    public str parmMessageId(str _value = messageId)
    {
        if (!prmIsDefault(_value))
        {
            messageId = _value;
        }

        return messageId;
    }

    [DataMember("SalesOrderNumber")]
    public str parmSalesOrderNumber(str _value = salesOrderNumber)
    {
        if (!prmIsDefault(_value))
        {
            salesOrderNumber = _value;
        }

        return salesOrderNumber;
    }

    [DataMember("CustomerAccountNumber")]
    public str parmCustomerAccountNumber(str _value = customerAccountNumber)
    {
        if (!prmIsDefault(_value))
        {
            customerAccountNumber = _value;
        }

        return customerAccountNumber;
    }
}

Create The Line Class

Repeat the same steps to create another class. I named mine ‘rsmTutOrderLineClass’. It looks like this:

[DataContractAttribute]
public class rsmTutOrderLineClass
{
    private str messageId;
    private real salesQuantity;
    private str itemNumber;
    private real discountPercentage;
    private str dlvTerm;
    private real discount;
    private real unitPrice;
    private real lineAmount;
    private date requestedReceiptDate;
    private str lineNumberExternal;
    private str dlvMode;

    [DataMember("SalesQuantity")]
    public real parmSalesQuantity(real _value = salesQuantity)
    {
        if (!prmIsDefault(_value))
        {
            salesQuantity = _value;
        }
        return salesQuantity;
    }

    [DataMember("ItemNumber")]
    public str parmItemNumber(str _value = itemNumber)
    {
        if (!prmIsDefault(_value))
        {
            itemNumber = _value;
        }
        return itemNumber;
    }

    [DataMember("DiscountPercentage")]
    public real parmDiscountPercentage(real _value = discountPercentage)
    {
        if (!prmIsDefault(_value))
        {
            discountPercentage = _value;
        }
        return discountPercentage;
    }

    [DataMember("DlvTerm")]
    public str parmDlvTerm(str _value = dlvTerm)
    {
        if (!prmIsDefault(_value))
        {
            dlvTerm = _value;
        }
        return dlvTerm;
    }

    [DataMember("Discount")]
    public real parmDiscount(real _value = discount)
    {
        if (!prmIsDefault(_value))
        {
            discount = _value;
        }
        return discount;
    }

    [DataMember("UnitPrice")]
    public real parmUnitPrice(real _value = unitPrice)
    {
        if (!prmIsDefault(_value))
        {
            unitPrice = _value;
        }
        return unitPrice;
    }

    [DataMember("LineAmount")]
    public real parmLineAmount(real _value = lineAmount)
    {
        if (!prmIsDefault(_value))
        {
            lineAmount = _value;
        }
        return lineAmount;
    }

    [DataMember("MessageId")]
    public str parmMessageId(str _value = messageId)
    {
        if (!prmIsDefault(_value))
        {
            messageId = _value;
        }
        return messageId;
    }

    [DataMember("RequestedReceiptDate")]
    public date parmRequestedReceiptDate(date _value = requestedReceiptDate)
    {
        if (!prmIsDefault(_value))
        {
            requestedReceiptDate = _value;
        }
        return requestedReceiptDate;
    }

    [DataMember("LineNumberExternal")]
    public str parmLineNumberExternal(str _value = lineNumberExternal)
    {
        if (!prmIsDefault(_value))
        {
            lineNumberExternal = _value;
        }
        return lineNumberExternal;
    }

    [DataMember("DlvMode")]
    public str parmDlvMode(str _value = dlvMode)
    {
        if (!prmIsDefault(_value))
        {
            dlvMode = _value;
        }
        return dlvMode;
    }
}

Create the Request Class

Now we are ready to create the rest of the objects needed for the service. When you create a custom service in D365, the Request class needs to have a variable for each piece of data you are sending into the system.

First, create a new class in Visual Studio. I named my ‘rsmTutRequest’.

Next, add the Attribute [DataContractAttribute] just above the class declaration.

Add a variable. I named mine ‘dataAreaId’.

Create a parameter method for that variable, and put the attribute [DataMember(“<The name of your Data>“)] above the method.

Your code should look like this:

[DataContractAttribute]
class rsmTutRequest
{
    private str dataAreaId;

    [DataMember("DataAreaId")]
    public str parmDataAreaId(str _value = dataAreaId)
    {
        if (!prmIsDefault(_value))
        {
            dataAreaId = _value;
        }

        return dataAreaId;
    }
}

Add The Header To The Request Class

Next, in this more complex example, add a parm method that will take in an entire class object. In our example, the service is taking in an entire sales order. We need to send in information for the sales order header, and information for the sales order lines. Let’s start with the header. Add the following code to the class, where the name of the class object is rsmTutOrderHeaderClass:

[DataMember("rsmTutOrderHeaderClass")]
    public rsmTutOrderHeaderClass parmrsmTutOrderHeaderClass(rsmTutOrderHeaderClass _rsmTutOrderHeaderClass = rsmTutOrderHeaderClass)
    {
        if (!prmIsDefault(_rsmTutOrderHeaderClass))
        {
            rsmTutOrderHeaderClass = _rsmTutOrderHeaderClass;
        }

        return rsmTutOrderHeaderClass;
    }

Note: In the value inside the [DataMember(“<property name>”)] does not need to match the name of the class. It should be whatever property name you will use in sending in the data. This could be a JSON or XML tag name.

Add The Lines To The Request Class

Next, in this more complex example add a parm method that will take in a List of class objects. In this example, these are the sales order lines. This is the key part of this article. Your code should look like this:

[DataMemberAttribute("rsmTutOrderLineClass"),
    DataCollection(Types::Class, classStr(rsmTutOrderLineClass)),
    AifCollectionTypeAttribute('_rsmTutOrderLineClassArray', Types::Class, classStr(rsmTutOrderLineClass)),
    AifCollectionTypeAttribute('return', Types::Class, classStr(rsmTutOrderLineClass))]
    public List parmrsmTutOrderLineClassArray(List _rsmTutOrderLineClassArray = rsmTutOrderLineClassArray)
    {
        if (!prmIsDefault(_rsmTutOrderLineClassArray))
        {
            rsmTutOrderLineClassArray = _rsmTutOrderLineClassArray;
        }

        return rsmTutOrderLineClassArray;
    }

The attribute above the parameter in this case is different to allow for an array or list of data to be sent in. Let’s breakdown and explain each line.

• [DataMemberAttribute(“rsmTutOrderLineClass”), – This lets the system know that when the data is sent in, it will use a JSON or XML tag named ‘rsmTutOrderLineClass’. This can be set to whatever your data tag is and does not need to match the name of your class.
• DataCollection(Types::Class, classStr(rsmTutOrderLineClass)), – This specifies the name of the class that the incoming data should be mapped to. In our case, the data we will send it will match the parm methods we have created in the rsmTutOrderLineClass class.
• AifCollectionTypeAttribute(‘_rsmTutOrderLineClassArray’, Types::Class, classStr(rsmTutOrderLineClass)), – This lets the system know that the name of our parameter in our Service class method will be named _rsmTutoOrderLineClassArray. (You can name the variable whatever you would like.) And that it will be a list of objects.
• AifCollectionTypeAttribute(‘return’, Types::Class, classStr(rsmTutOrderLineClass))] -This tells the system that parm method will return a list of objects of type rsmTutOrderLineClass

Create The Response Class

The Response class does not change from our system example. The class needs to have a variable for each piece of information we would like to send back to the calling program.

First, create a new class in Visual Studio. I named mine ‘rsmTutReponse’.

Add the attribute [DataContractAttribute] just above the class definition.

Add variables that will contain information you want to return to the calling program. I created variables ‘success, ‘errorMessage’, and ‘debugMessage’.

Finally, create a parameter method for each of your variables. Put the attribute [DataMember(“<The name of your data>“)] above each method definition. The value you put as <The name of your data> will be the name of the JSON tag that is generated.

Your code should now look like this:

[DataContractAttribute]
class rsmTutResponse
{
    private boolean     success;
    private str         errorMessage;
    private str         debugMessage;

    [DataMember("ErrorMessage")]
    public str parmErrorMessage(str _value = errorMessage)
    {
        if (!prmIsDefault(_value))
        {
            errorMessage = _value;
        }
        return errorMessage;
    }

    [DataMember("Success")]
    public Boolean parmSuccess(Boolean _value = success)
    {
        if (!prmIsDefault(_value))
        {
            success = _value;
        }
        return success;
    }

    [DataMember("DebugMessage")]
    public str parmDebugMessage(str _value = debugMessage)
    {
        if (!prmIsDefault(_value))
        {
            debugMessage = _value;
        }
        return debugMessage;
    }
}

Create A Complex Service Class

Now that we have finished the Request and Response class, we will look at what is new when we create a complex Service in D365. The Service class is the most interesting class when you create a custom service in D365. It is responsible for reading values from the Request object, running some process, then setting values on the Response object.

First, create a new class in Visual Studio. I named mine ‘rsmTutService’.

Create a method in the class, named whatever you would like. I named mine ‘create’.

The method needs to take as a parameter which has a type of your Request object. And it needs to return a value which has a type of your Response object. This is my example method definition:

public rsmTutResponse create(rsmTutRequest _request)

Inside the method, I have written code to read the header object from the request object, using the parm method, and pass it into a method named ‘createHeader’. This method is responsible for reading values from the header class object. In my case storing the values into a staging table.

Next, I have written a ListIterator to loop through the array or list of line objects that were sent in as part of the request. For each object, I call the method ‘createLine’. This method is responsible for reading values from the line class object. In my case storing the values into a second staging table. The full code of my service is below:

public class rsmTutService
{
    public rsmTutResponse create(rsmTutRequest _request)
    {
        List lines;
        ListIterator   literator;
        rsmTutOrderLineClass rsmTutOrderLineClass;
        int i;

        var response = new rsmTutResponse();
        changecompany(_request.parmDataAreaId())
        {
            try
            {
                this.createHeader(_request.parmrsmTutOrderHeaderClass());

                //Create lines
                lines = _request.parmrsmTutOrderLineClassArray();
                if (lines)
                {
                    literator = new ListIterator(lines);
                    while (literator.more())
                    {
                        rsmTutOrderLineClass = literator.value();
                        this.createLine(_request.parmrsmTutOrderHeaderClass(), rsmTutOrderLineClass);
                        literator.next();
                    }
                }

          response.parmDebugMessage(_request.parmrsmTutOrderHeaderClass().parmMessageId());
                response.parmSuccess(true);
            }
            catch (Exception::CLRError)
            {
                System.Exception interopException = CLRInterop::getLastException();

                response.parmSuccess(false);
                response.parmErrorMessage(interopException.ToString());
            }
            return response;
        }
    }

    public void createHeader(rsmTutOrderHeaderClass _rsmTutOrderHeaderClass)
    {
        rsmTutOrderHeader rsmTutOrderHeader;
        rsmTutOrderHeader lastrsmTutOrderHeader;

        rsmTutOrderHeader.MessageId = _rsmTutOrderHeaderClass.parmMessageId();
        
        select firstonly lastrsmTutOrderHeader
            where lastrsmTutOrderHeader.MessageId == rsmTutOrderHeader.MessageId;

        if (lastrsmTutOrderHeader)
        {
            // throw error about duplicate order header
            throw Error(strFmt("A message with message ID %1 already exists"));
        }
        else
        {
            rsmTutOrderHeader.Status = rsmCommerceOrderStatus::ToBeProcessed;
        
            rsmTutOrderHeader.CustomerAccountNumber = _rsmTutOrderHeaderClass.parmCustomerAccountNumber();
            rsmTutOrderHeader.SalesOrderNumber = _rsmTutOrderHeaderClass.parmSalesOrderNumber();
            rsmTutOrderHeader.insert();
        }

    }

    public void createLine(rsmTutOrderHeaderClass _rsmTutOrderHeaderClass, rsmTutOrderLineClass _rsmTutOrderLineClass)
    {
        rsmTutOrderLine rsmTutOrderLine;

        rsmTutOrderLine.MessageId = _rsmTutOrderHeaderClass.parmMessageId();
        rsmTutOrderLine.LineNumberExternal = _rsmTutOrderLineClass.parmLineNumberExternal();
        rsmTutOrderLine.ItemNumber = _rsmTutOrderLineClass.parmItemNumber();
        rsmTutOrderLine.SalesQuantity = _rsmTutOrderLineClass.parmSalesQuantity();
        rsmTutOrderLine.UnitPrice = _rsmTutOrderLineClass.parmUnitPrice();
        rsmTutOrderLine.Discount = _rsmTutOrderLineClass.parmDiscount();
        rsmTutOrderLine.LineAmount = _rsmTutOrderLineClass.parmLineAmount();
        rsmTutOrderLine.DiscountPercentage = _rsmTutOrderLineClass.parmDiscountPercentage();
        rsmTutOrderLine.RequestedReceiptDate = _rsmTutOrderLineClass.parmRequestedReceiptDate();
        rsmTutOrderLine.DlvMode = _rsmTutOrderLineClass.parmDlvMode();
        rsmTutOrderLine.DlvTerm = _rsmTutOrderLineClass.parmDlvTerm();
        rsmTutOrderLine.insert();
    }
}

Create The Service Object

The Service object, exposes our Service class and allows it to be called by an outside system with the proper authentication. In Visual Studio, right click on your project, and select ‘Add New Item’. Then select ‘Service’.

Give the item a name. I named mine ‘rsmTutServiceSimple’

Open the object. Right click on it and select ‘Properties’

In the Properties window, set the ‘Class’ property with the name of the Service Class you created earlier. Mine is named ‘rsmTutService’. (The same as the service object). Also, set the ‘External Name’ property to the same value. You can change this to be whatever you want. But it is simpler if you leave it the same.

Now, Right click on the ‘Service Operations’ node, and select ‘New Service Operation’.

Select the new node that is created, and in the Properties window set the ‘Method’ property to the name of the method in your Service class. I named mine ‘create’. Also set the ‘Name’ property to be the same. (You could change this to be something different. But it is simpler if you set it to be the same as the method name).

Create The Service Group

The Service Group is an object that can contain one or more services and is a way of organizing similar operations together.

In Visual Studio right click on the project and select Add>New Item. Select the ‘Service Group’ item. Then give your object a name. I named mine ‘rsmTutServiceGroup’.

Open the new Service Group object, and right click on the main node. Select ‘New Service’ from the drop down.

Select the node that is created, and view the properties window. Set the ‘Name’ and the ‘Service’ properties to the name of your Service object. In my case, the name of my Service object is ‘rsmTutServiceSimple’.

Call The Service From Postman

You just learned how to create a complex Service in D365, now you need to call it. You can view the previous article for detailed steps on how to use Postman to call the service. In this case the URL to call the service will be:

https://<D365 URL>/api/services/rsmTutServiceGroup/rsmTutService/create

Let’s break down this URL into it’s parts.

• https:// – This specifies we are making a secure call.
• <D365 URL> – This should be replaced by the URL used to access your D365 environment. For example: https://usnconeboxax1aos.cloud.onebox.dynamics.com
• api/services – This text tells D365 that we are calling a service.
• rsmTutServiceGroup – This is the name of the service group we are calling.
• rsmTutService – This is the name of the service we are calling.
• create – This is the name of the method we are calling on the Service class.

In this example the Postman body is more complex. The header information as well as an array of line information needs to be sent in. Note: In JSON, an array of data is wrapped in square brackets like this [ ] My example looks like this.

{
	"_request" :
	{
		"DataAreaId": "USRT",
		"rsmTutOrderHeader" :
		{
			"MessageId": "1234",
			"SalesOrderNumber" : "SO1234",
			"CustomerAccountNumber" :"C000137"
		},
		"rsmTutOrderLineClass" :
		[
			{
				"LineNumberExternal": "1",
				"ItemNumber": "MyItemId",
				"SalesQuantity": 1,
				"DiscountPercentage": 10,
				"Discount": 0.1,
				"UnitPrice": 6,
				"RequestedReceiptDate": "12/15/2021"
			},
			{
				"LineNumberExternal": "2",
				"ItemNumber": "MySecondItemId",
				"SalesQuantity": 4,
				"DiscountPercentage": 10,
				"Discount": 0.1,
				"UnitPrice": 7,
				"RequestedReceiptDate": "12/15/2020"
			},
			{
				"LineNumberExternal": "3",
				"ItemNumber": "MyThirdItemId",
				"SalesQuantity": 6,
				"DiscountPercentage": 10,
				"Discount": 0.1,
				"UnitPrice": 8,
				"RequestedReceiptDate": "12/15/2020"
			},
			{
				"LineNumberExternal": "4",
				"ItemNumber": "MyFourthItemId",
				"SalesQuantity": 1,
				"DiscountPercentage": 10,
				"Discount": 0.1,
				"UnitPrice": 9,
				"RequestedReceiptDate": "12/15/2020"
			}
        ]
	}
}

Conclusion

You have now performed the actions to create a complex service in D365 as well as call it! Awesome job! Now any outside system can call code inside of D365. As well as send in complex information. This can be used by Microsoft Power Apps, Power Automate, Azure Logic Apps, other externals systems, and many more. Enjoy!